The Secret to Good Technical Documentation

The secret to good technical documentation is to write it the same way you write code. Step by step, leaving nothing out, each step in logical sequence.

This is harder than it sounds. Most techies aren’t professional writers. Their last experience of writing documents may be back in high school and, while well able to do it, the messages they remember from their schooling may have become a little crossed as their priorities changed in college and on into adulthood and professional life.

For which reason, when a techie sits down to write, she may hear the echo of her teacher’s voice telling her to jazz up the thing a bit, and give it a bit of spice. And that’s fine if you’re a jazzy, spicy writer. If you’re not, for God’s sake don’t try to be because you’ll only fall flat on your face. (The same thing applies to adding jokes to best man speeches at weddings, by the way. Know your limits).

When a child graduates from elementary school, one of the things she’s told is that short sentences are bad. They’re not. Short sentences are great. Nothing other than short sentences are bad, just like an excess of anything is invariably bad, but short sentences are just as good as any other sentence, and often better than most. This is especially true if writing is not your primary job, as it won’t be if you’re a techie being asked to write documentation.

Try to keep your sentences short and to the point. Don’t forget, people aren’t reading documentation for leisure. There’s only one reason that people read documentation, and that’s to find something out. Ideally, to find something out as quickly as possible. In writing documentation, the question every techie should ask herself is: is the reader closing to finding out what she wants to know having read this sentence? If so, great. If not, why not, and can it be fixed?

Documentation gets better with practice, but practice isn’t something that can be done in isolation. All practice needs a feedback loop, or else you just end up practising the same mistake, and where’s the good in that?

Technical writing is unusual in that it requires two distinct proofreaders. The first is to check for accuracy - does the code what you say it should do? Are your code examples correct? That’s straightforward.

The trickier part of proofing is finding someone who can’t check for accuracy, because she doesn’t have the first notion what is accurate and what isn’t. She is the target audience and, if she can’t do what you’ve described in the documentation, then your documentation has exited with a value of minus one, and you have to write it again.

The problem then is finding another proof reader who is as innocent of what you’re doing as the first one was, and then having her read it and see if she can understand it. You can’t use the same one as, sadly, there is no clear cache button on the human being.