Technical Writing, Writing, and Having More Fun as a Techwriter

My friend Kathy has posted recently about techwriting.

Not to suck up or anything but she's dead on. She was posting for folks who aren't professional techwriters, though, and I wanted to ramble on a bit, as a professional techwriter, and for those who are or who might be interested anyway.

I've been in and out of techwriting for 15 years and I learned long ago that manuals sometimes suck because they're software bandaids. In fact, I made a design on my www.cafepress.com/techright store a while ago with the Techwriter's Crest, which included a bandaid across a picture of a CD. When a manual is complicated, it's sometimes because it's full of things like "Don't ever hit the OK button, it will corrupt all your data if you've entered a new record before running the Mogonshloggin rebuild function" and worse. Manuals can't be very good when the software is terrible. There's still some wiggle room, of course.

Manuals are also complicated because, as Kathy says, the software requires that the users put in stuff they don't know. The fields in the windows you're working in should ask for what you know. Ask for whether the user already has their addresses or whether they need to add new addresses, not whether they want to import ASCII or add comma-delimited records on the fly. Or ask the user for a number they have and then do the computation for them; don't ask them to do the computation first. (That's why the machines are called....computers.)

So that's what we're stuck with. But there's also some control. And the more you get to be in control and use your brain and think of cool ways to make the docs better, the less you hate your job and wonder why you didn't take that opportunity to be a property manager in the Andes when you had your chance.

What do we do to like our jobs and do good work?

Think about what's important. And if you're working on something important, and using your brain, it all flows from that.

What's really important?

I'm not saying throw your English major out the window, but spending cycles on the stuff that doesn't help and that nobody will notice robs you of time you could spend learning the product.

There are editors and  techwriters out there who care more about parallel structure and "onto" versus "into" and serial commas than well-organized getting started manuals. There are techwriters out there who just copy and paste the spec, and never verify it, never take donuts down the hall to the developers, and never take initiative to figure out if things could be done better. And that makes for unhappy techwriters and unhappier users. So as tough as it is sometimes, get out of the corporate torpor and you'll make better products by focusing on the things your users need.

Here's a link to the grammar stuff that I think is important; one of my previous writing blogs.

Sometimes it's hard to get anywhere, because of a culture of treating the techwriters as second class citizens (and QA doesn't get treated much better), sometimes it's the individual writers' faults, sometimes it's both. But techwriting is not about the words or the style or the bullets, and it certainly can't be looked at in a vacuum. It's the guidance for how to use the product.

And if you don't need that much guidance to use the product, then you need less documentation. And the documentation that there is, is easier to follow.

Which leads me to another soapbox topic. A fundamental flaw in bad documentation is when you try to document the features, the product, the software, rather than talking about how the user should do what she needs to do. Documenting a zillion windows, just because they're there, in a 200-page appendix, is not as good a use of your time as talking to users, doing a little task analysis if you like to use that jargon, figuring out what the things are that people will be doing, and documenting how to do those things.

It's harder for writers to document tasks than features, but you just do that once. And there are, you hope, a lot of users who will be frustrated each time they read the manuals.

1 x a lot of work  < 10,000 x a lot of work

(Now, sometimes the product is hard. If you're documenting how to use a ten zillion feature storage device, say a McDATA I10k Director that stores a zillion and a half gigs of very important information, things might get a little complicated and the manuals reflect that. But still -- the same guidelines apply, it's just harder.)

When I was at Great Plains Software, now part of the Microsoft empire, we had a huge manual called the Field Descriptions Manual. 600 or so pages, 6-point type, and just a huge bunch of info about all the fields and files in the software, for our developers.

Now, that's a horrible thing to write, to edit, and to use.

What we switched to, when I was there, was online field descriptions. The code in the product knows how long all the fields are, and what the type is, and what the name of the files are. The code couldn't run if it didn't, eh? So some clever lad wrote a program that sucked out that data and displayed it in a nice tidy little program. Very easy to use. The manual was maybe 10 pages. And guess what -- the online field descriptions were always up to date and accurate.

So here's what can make life more fun and the docs better. Not "First prize in the STC" better, but truly better, better for our  users.

Goals for Techwriters

• Think about what's important. Throw out everything, take a couple hours off with the team early on a Friday afternoon, and figure out what's important. Work on that.
• If you have any design input, try to make the product give the information, or figure out the information, not the person. Maybe rename some menus, try to get things organized logically.
• Make the documentation task-oriented, not feature-oriented.
• Talk to a user. Talk to a lot of them. It'll change your life and how you approach documentation. Go to a training class with real customers. When I taught my first class with my first workbooks, I....well, let's just say the workbooks have changed a lot since then.
• Try to get to those product meetings.
• Get to know the developers. It's not fair that they have all the info and you don't, but if you get to know them they'll tell you stuff. Just basic human interaction. It's a lot more effective than rules and processes and meetings.
• Dare to skip stuff. If people can easily see that the Badger dialog box displays the name and ID of the current badger, why spend time documenting it?
• Remember good techwriting is harder but more fun.  Otherwise you're just filling out TPS reports and thinking, as you sit in the bathroom killing time til you get back to your desk, that you only have to do this for 20 more years.
• Keep a quoteboard. It doesn't help with your techwriting but it's fun.

Am I curently a techwriter? Off and on. I prefer training because -- well, I'm charge, I don't have to coax the developers to give me information, and the training is the product. Plus I get to see the light bulb go on. But I do periodic techwriting projects still, I'm still connected. I know it's tough and there's always something annoying going on. But if it were easy or fun all the time, then it would be harder to get into and lower-paid, right?

I'll sign off with my favorite quotes about writing.

"When I am a rich man with my own bicycle and can have beer for breakfast I shall give up writing altogether and just be absolutely disgusting." Dylan Thomas

"Be a scribe! Your body will be sleek, your hand will be soft...You are the one who sits grandly in your house; your servants answer speedily; beer is poured copiously; all who see you rejoice in good cheer. Happy is the heart of him who writes; he is young each day." Ptahotep, 4500 B.C.

"Documentation is like sex. When it's good, it's very, very good. And when it's bad, it's still better than nothing!"

Comments

[Monique]

Hi,

My company is one of the three major credit bureaus; A group of internal clients I support is in need of a great technical writer willing to build from the ground up. We are located in Southern California. If you know of anyone in this area seeking a position or someone who would like to relocate for this position, could you please send me an e-mail with their contact information?

Thanks,

Monique

[Intechs]

Yes, documentation is like sex. LOL

[Virginia]

The sex comment is yours? Thanks, it's one I'll remember. Have a good one!

[Loren]

My tag line: Writing is a socially acceptable form of schizophrenia~E.L. Doctorow

Loren

[tiffany bangles]

good