It’s Really a Simple Process…
March 24th, 2008, 4 Comments »
From the men’s room at Workspace:
I like their frank procedural writing. And, toilet soakers, shouldn’t this have been thoroughly covered by grade two?
Archive: Posts about Technical Writing
Tearing Down and Reinforcing Gender Stereotypes, All in One Sentence
February 4th, 2008, 14 Comments »
I was just re-reading a whitepaper I’m writing, and encountered this sentence:
If the lead developer on an open source project takes maternity leave, there aren’t necessarily resources to replace her.
I made a software enthusiast female–yay! And yet she’s threatening the project to go have babies–boo!
Fear not, this is just the first draft, but I had to laugh at my own, uh, misguidedness.
There Are No Frickin’ Cross References in Apple’s Pages?
December 8th, 2007, 17 Comments »
We’re spending the weekend putting the final touches on our ebook, and planning our marketing push. I’m doing the final layout work on the book, and one of the last things on my list is adding cross references. You know, sentences like “for more information on Facebook, see page 46″. We’re using Pages 2.0, part of Apple’s iWork ’08 suite. I started clicking around the menus to finding the cross reference functionality, and couldn’t. You know why?
Pages doesn’t offer cross references.
I am seriously underwhelmed. Cross references are a pretty basic feature for word processor software. After all, Microsoft Word has had them for about 15 years. Apple wants me to use Pages to make “newsletters, reports, proposals”, but they want me to hard code the frickin’ page numbers?
It’s not an enormous pain now, but it will cause serious angst every time we update the book. Once we introduce a few paragraphs of new content, every cross reference will be wrong.
I’m extra disappointed because Pages has otherwise proved an excellent, reliable tool with few bugs, and a real improvement on alternatives MS Word (on reliability) and Framemaker (on usability).
Keep Marketing Away From the Manuals
August 30th, 2006, 29 Comments »
Most days, I straddle the Berlin Wall between product development and marketing. I used to work amongst the programmers as a technical writer. At Capulet, we don’t do software documentation anymore. However, for a lot of our clients, we’re the Checkpoint Charlie between the people who make stuff and the people who promote and sell stuff.
Seth Godin links to Kathy Sierra’s thinking about why “marketing should make the user manuals”:
Why do so many companies treat potential users so much better than existing users? Think about it. The brochure is a thing of beauty, while the user manual is a thing of boredom. The brochure gets the big budget while the manual gets the big index. What if we stopped making the docs we give away for free SO much nicer than the ones the user paid for? What if instead of seducing potential users to buy, we seduced existing users to learn?
She also provides a graphic illustrating that marketing material is ‘glossy, slick, colourful’ while manuals are ‘plain, dull, black and white’.
This is an incredibly wrong headed idea:
- The user has already bought the product. They want to know how it works, not why it’s good. Often the people using the product are not the people who bought it. They don’t care why it’s good. They just want to know how (not why) it will make their lives easier.
- Seth Godin said it best: all marketers are liars.
Marketers are trained to obfuscate, exaggerate, denigrate and spin. Those are useful talents, but not when you’re trying to explain how things work. - Of all the software marketers I’ve met, only a small fraction has the technical background to thoroughly understand and explain their products. Go ask some folks in BEA’s marketing department how to, say, deploy a message-driven EJB, and see how they do. This isn’t a criticism. Most marketing doesn’t require an in depth understanding of the thing you’re promoting. It helps and is something you should aspire to, but it’s also pretty uncommon.
- Technical writing is a skill set that’s significantly different than marketing. In additional to the technical know-how, you need industry-specific tool knowledge, an understand of usability, instructional skills and so forth.
There’s a reason why words like ‘glossy’ and ‘slick’ have negative connotations. Because they imply shallowness, which isn’t something you should aspire to in a user manual.
It’s hubris to say, as Kathy does, that “shouldn’t we be using all that graphic design and pro writing talent for the people we care about the most?” Ah right, so there hasn’t been any design or ‘pro writing talent’ applied to that area yet? And marketers are the saviours? Right.
User manuals get a bad wrap because companies don’t devote enough resources to them. That money should be spent on thoughtful tech writers, trainers and support personnel who can make compelling training and support material. It shouldn’t be spent on applying lipstick.
In truth, manuals are frequently an admission that by a company that they didn’t design the product well enough. Do you really need a manual for an iPod? Check out the help system in the Apple OS. It sucks. Why? Because it’s so rarely referenced by the user.
The people who sell the product shouldn’t be writing about how the product works. Why not? Let’s revisit BEA. I’m not picking on them, they’re just the first company with a complicated product offering that sprang into my head. Visit the product page for BEA WebLogic Server. Presumably marketing wrote it. The first paragraph of text reads:
Your business can’t afford to have your application server fail. BEA offers an application server built for mission critical applications and service-oriented architecture (SOA). The proven Enterprise Grade Kernel keeps your applications up and running even when deploying a new version, changing the server configuration or failing over within or across data centers.
Then check out the introduction in the manual for the latest version of BEA WebLogic Server:
BEA WebLogic Server is a scalable, enterprise-ready Java Two Enterprise Edition (J2EE) application server. The WebLogic Server infrastructure supports the deployment of many types of distributed applications and is an ideal foundation for building applications based on Service Oriented Architectures (SOA). SOA is a design methodology aimed at maximizing the reuse of application services.
One sells. The other tells you what the product is and does. Having already purchased the thing, which would you rather read?
UPDATE: I believe this Dilbert cartoon expresses my sentiments nicely.
Seeking a Junior Contract Technical Writer
December 19th, 2005, 5 Comments »
We’ve got a project starting in late December with which we need some help. We’re looking for a junior writer to do about 40-45 hours of work through the end of January, 2006. If we’re happy with your work, there will no doubt be more projects in 2006.
By junior we mean that you’ve had a couple of years experience in the industry, and understand the tools and terminology. You’ll be assisting a senior writer on a project. We’d definitely prefer it if you lived in Vancouver or area, but it’s not essential. We don’t want to hear from you if you’ve been a technical writer forever and wrote the help system for Windows 3.1.
If you are such a person, or know anybody who fits these criteria, drop me an email.
The Gomery Report is Surprisingly Readable
November 2nd, 2005, 2 Comments »
I didn’t believe Derek when he made this point, but then I hadn’t actually looked at the official report (it’s got it’s own URL, too). For those non-Canucks out there, Justice Gomery is investigating a major political scandal that recently occured in Quebec.
As Derek notes, “Gomery wrote the report itself in the first person, using the active voice in places you’d never expect it.” Here’s a sample paragraph from the Who Is Responsible section:
The notion that Mr. Pelletier and Mr. Gagliano could provide political input without strongly influencing the decision-making process is nonsense and ignores the obvious reality that the expression of an opinion to a subordinate official by the Prime Minister’s Chief of Staff or the Minister amounts to an order.
Well done, Mr. Gomery! My only complaint is that the individual sections of the report are apparently only available in PDF.
Should I Become a Technical Writer?
July 15th, 2005, 12 Comments »
Over at Ask Metafilter, somebody asked that question. As a former technical writer myself, I was interested to read the discussion. Here’s the worst advice I could find:
To do this job well, of course, you practically need to be a programmer yourself, and today that means knowing not just the basics of how to code in some language (something C-derived is a must), but also things like design patterns and development methodologies.
I have worked as a technical writer, mostly, since 1982. It is a hard, grueling job. I honestly can’t recommend it if you have alternatives.
If you plan to work in software, as most technical writers do, I recommend taking an introductory, theoretical course in programming. I’d also suggest you read a couple of books on the software development process. The book that helped me the most was Software Project Survival Guide. This research ensures that you can at least speak some of the lingo and have an understanding of whta, say, ‘unit testing’ is.
As for technical writing being a ‘hard, grueling job’, that’s just laughable. I can’t find it now, but I read a study that found technical writing to be one of the least stressful jobs around. It can get busy around release dates, but it’s very cyclical. After the product is released, there’s often a lot of downtime.
And the best advice?
If you already have a B.A. you will be very seriously dissapointed by a Technical Writing program at a community college.
While communication skills are only a part of a tech writer’s skill set, a B.A should give you 80% of that set.
My Brother’s Business and Blog
July 5th, 2005, 4 Comments »
My brother Kevin is a writer as well. His day-job is as a technical writer at Creo, a recently-acquired subsidiary of Kodak. He’s also launched a recent white paper-writing business called (funnily enough) Barefoot White Papers. He’s got a nifty blog there all about white papers, which I enthusiastically recommend.
Now we also do white papers at Capulet, so he’s kind of competition, but there’s plenty of work to go around.