• Home
• Services
• Writing
• About
• References

Writing Good Documentation

As stated in the document "Writing and Programming - Next of Kin", writing isn't all that different from making efficient software. The essentials can be boiled down to:

1. Write an outline
      (Too late to start)
2. Write the document
      (Too early to stop)
3. Edit the content
4. Edit the language
5. Repeat steps 3 and 4

1. Write an Outline

This is not all that different from writing your typical requirements and design-documents.

First

you need to make clear exactly how your document will make the world a better place and as important: who are you writing for, who is your target group? Is your document for other developers, system administrators, end users or business people?

If you don't declare your target audience you're off to a very bad start - the target audience defines the rest of the writing process, and without it you wont be able to make any sound decisions about your writing.

Second

you decide on the structure of the document. Does A really come before B or would it make more sense to start out with B? Or C?

Third

you should decide how to use the language. The target audience should pretty much make this a no brainer. If you're writing for other developers a certain degree of technical terms doesn't give rise to any problems, but if the audience is less technical oriented, maybe you should hold back on the geeky phrases.

All of the above seems obvious, but too often people just knock out a piece of documentation without paying too much attention to target audience, outline or language usage. To prove this point, here's something I once overheard from one of my developer colleagues who was asked out for lunch:

"Yeah, I'll be with you shortly - I just have to write up some documentation for this thing..."

In the ears of a writer this makes as much sense as the following would to a programmer:

"Yeah, I'll meet you there - I just have to code this workflow engine from scratch..."

2. Write the Document

Now that you've got the target audience, document structure and style of language clear, it's time to start writing. If you've followed the steps above, writing the document shouldn't be too hard - just as coding a piece software isn't all that hard if you've clearly defined the requirements and design.

Exactly how hard this part is and how well the thing turns out depends on your writing experience and your natural talent for writing. But even without talent and with little experience, a thorough preparation should ensure a reasonable document.

3. Edit the Content

Once you're done with your first draft of the document you need to make sure that the content is coherent.

Working on a project for weeks or months tends to make you blind to the fact that other people live different lives than yours. Not everyone can match your level of knowledge on the subject you're writing about, and you need to make sure that the text doesn't build on top of knowledge that it doesn't provide - if there are any prerequisites to understand the document, list them in the very beginning.

You also want to make sure that your document answers all questions it might rise. Squeeze your brain to figure out which questions people could possibly ask after reading the document. Have someone unfamiliar with the subject read the text to drain it for all open questions. Then implement the answers in the document.

4. Edit the Language

After passing the tests in the previous section, you can start looking at the language itself. This is where you can make a difference and make your personal voice heard. This is also the hardest part.

You can bury a totally exciting point in language so boring that people never get it. Do your part of the job and ensure that your language is lively and interesting - by doing so you make the readers' part of the job so much easier.

Since you know everything about the subject that you're writing about, the biggest danger is that you see through the language and only care about getting the facts right. This is no crime but there's no reason that your text shouldn't be as digestible as possible. This requires some focus on the language itself. Take a look at this quote I once found in a piece of documentation for a workflow package:

The text explains what the workflow package does, so everything is fine. Or is it? The text doesn't really qualify as very interesting and the only truly remarkable thing about it is that it contains a sentence of more than 350 characters. The latter is impressing but not likely to enhance readability.

A little editing turned the text into this:

Wow, what a difference. Not only are the sentences more well-balanced but now we have a metaphor, which always makes a text lively and digestible. This metaphor even makes explanation of all aspects of the workflow engine easier since there now is an easily perceptible picture to relate to (the 'old-fashioned' office).

Mine your text for opportunities to clean up and rephrase into something more interesting than just a grammatical correct presentation of facts.

5. Repeat Steps 3 and 4

Edit your document and have it edited by others as many times as you can possibly bear. You'll meet a natural limit where you just hate the text more than anything - this would be a good time to put it away for a while.

Here's a couple of practical hints to how you can work with your text:

• Can you in five seconds - and preferably in one sentence - explain what the purpose of the document is? If not, you should rethink the stuff sketched in the top of this page.
• Have someone unfamiliar with the subject read your text. Ask her if she had to read anything twice to understand it. If she did, chances are that those phrases or sections aren't clear enough.
• Read your text out loud. Yes, I'm serious. You don't get an idea of the rhythm in a text if you can't hear it. Take it to the kitchen, the bathroom or wherever and READ.
• Can anything be clarified by supplying a metaphor picturing the message?
• Would an illustration aid the understanding of what you're trying to say?
• Does the length of your sentences vary - is there a rhythm, or are you just grinding, monotonously away?
• How's the physical structure? Make a print of your text and look at it from a distance. If you see nothing but huge chunks of ink, you should probably try to split it up some more - too large blocks of text tend to bore the eye.
• Never finish a document in just one day. Always revisit it the day after to see if you turned blind on something the day before. Chances that you did are pretty damn good.
• Get rid of all misspellings. This seems obvious but somehow glitches always find their way into the final distribution. Misspellings signal incompetence, but more importantly, they annoy the eye of the reader.

And never forget that everyone needs an editor.