I earn (what could laughably be called) my living as a technical writer, and I thought I’d share a few things I’ve learned about the trade.
The hardest part is getting the information. Technical writing is more than just sitting at a word processor and cranking out paragraphs. You have to go out there and get information from people. And these people are usually very busy; talking to technical writers ranks slightly below going to the water cooler on most people’s list of priorities.
Usually, you have to physically travel to the other person’s desk to get the information you need. People almost invariably ignore email. A polite, friendly, but persistent approach is usually the most effective.
The second-hardest part is understanding and organizing the information. After all, if it wasn’t complicated and hard to understand, they’d have an administrative assistant write it up for half your salary.
Sometimes, not knowing anything about a subject is very handy for a technical writer. After all, your readers aren’t going to know anything about the subject when they start reading. What you need to know to understand the subject is what they need to know, too. And you can figure out the order in which they need to know it.
The writing is the easiest part. Okay, there are some rules you have to remember – active voice good, passive voice bad; be task-oriented whenever possible – but the actual writing isn’t that hard if you’ve organized everything beforehand. You don’t need a fancy vocabulary to be a technical writer – your readers aren’t necessarily going to understand big words, so you shouldn’t use them.
Check your ego at the door. For the most part, people don’t want to see any evidence of personality in their technical documents. Reading documentation is like visiting the dentist – they want to get in, get it done, and get out as quickly as possible. (That’s one of the reasons why I write a blog and other things – I want to be able to rock and roll a little in my spare time.)
It’s not done until your manager says it’s done. Any document you write – no matter how complete it seems to you – is not complete until everybody with clout has agreed that it’s complete. All other versions of the document are drafts. Always be prepared to rewrite.
Get to know the developers. They’re the ones who have the information you need; you can’t function without them. They’ll also be the first to know if your product changes: if your organization is dysfunctional, this may be the only way that you’ll find out whether your documents need to be updated.
Always keep the document as complete as possible. It’s a bad idea to put “TBD” in a section, or notes to yourself (“Dave, fix this”) in a document. Just leave the incomplete sections out until you get to them. Here’s why: some senior manager may suddenly want the latest version of the document to give to an unexpected client, and he or she will want a “complete” version.
Do the screen snaps last. The look of the application you are documenting will always change about 11 times at the last minute. You don’t want to have to do the same work 11 times.
Sometimes, you have to suck it up. Technical writers have to ask people dumb questions; it’s part of our job. And some of these people are going to talk down a bit to you when they answer the questions. After all, they are Code Gods, and all of this is perfectly obvious to them. Just nod, smile, and write down what they tell you. Comfort yourself by realizing this: while you can’t do their jobs, they can’t do yours either.
People probably won’t read what you write. Many people don’t bother reading the manuals. They just go ahead and try the product. If you’re looking for fame, this isn’t the profession for you.
And a couple of notes for anyone who employs technical writers and happens to be reading this:
Please, please show up for your meetings. Because technical writers are low on the food chain, managers and developers often blow off meetings with writers in favour of more productive activities, such as toenail clipping. We have schedules too, goddamn it; help us meet them.
For the love of God, don’t ask us to take notes at meetings. Just don’t. Okay?