« If Google did Archaeology... | Main | Day Three as a Teaching Assistant »

How Not to Write Software User Documentation

There are few things that make my heart sink more than software user documentation that is just a description of the software's menu items and dialog boxes.  When I go to user documention, I do not go to it in order to find out whether the File menu has an Open option, nor whether I can use the latter to select a the file I want to open.  This sort of thing is obvious to almost everyone nowadays, and where it is not obvious it can be found by looking up and down the menus and at the dialog boxes themselves.

If you are a writer of software user documentation and you ever find yourself tempted to write user documentation like this, then I recommend that you first read the following words of advice taken from 'Read Me First, A Style Guide for the Computer Industry' (2nd Edition, published by Sun Microsystems Inc, 2003):

As a writer, you research, organize, and communicate information for the reader, who depends on you. In your relationship with the reader, you are the expert. Keep this point in mind when you make decisions about what information to present and how that information addresses the reader's questions.

Often a product provides several different ways to accomplish a single task. You might decide that you owe the reader an explanation of each method. However, remember that the reader is more interested in using the product than in understanding all options. Choose the best method for most of your audience, and tell the reader to use that method.
After you commit to the best course of action, you might explain to the reader that other methods exist. Tell the reader where to find your descriptions of those methods. Also tell the reader why and in what situations options A, B and C are useful.

(You will also be doing your readers a service if you tell them clearly when something is difficult, or impossible to do, rather than remaining silent and leaving them to find out for themselves.)

One of the most important contributions a writer makes is to anticipate the reader's questions and provide appropriate answers. A writer must anticipate questions about related topics as well and provide cross-references to where those questions are answered. As the subject matter expert, a writer can create a climate of understanding that is far more significant than merely recounting facts about the product.

See that?  The job of a writer of software user documentation is to "create a climate of understanding", not just to recount a list of facts about the product!

Reader Comments

There are no comments for this journal entry. To create a new comment, use the form below.

PostPost a New Comment

Enter your information below to add a new comment.
Author Email (optional):
Author URL (optional):
All HTML will be escaped. Hyperlinks will be created for URLs automatically.