How to write user documentation

In many software houses, software developers produce documentation for end users. If you are given the task of producing a user guide, a reference manual, or an online help system, where do you start? This article gives you guidance.

The business case

Typical reasons for producing user documentation are to:

Before you start to produce the documentation, identify the reasons for producing it. If it's not likely to improve overall profits, don't produce it. For example, it may be cost-effective to deal with a few additional phone calls to your support desk rather than providing comprehensive documentation. (You may need to provide documentation for regulatory or legal requirements—check with your legal team.)

Don't produce documentation to explain a clunky product. Instead, redesign the interface. I once showed a company how to reduce a fourteen-screen installation process to a single screen. The software had evolved over many years, and the developers did not see what was obvious to an outsider. So, obtain professional help from a usability expert.

Audience analysis

It's no use producing documentation that is written well, attractive and easy to use if it doesn't answer the questions that users ask. Therefore, before starting to write, you need to know about the intended audience and the tasks they perform.

Some users may be competent at using Windows and may be subject matter experts in their field, but they may have never used your software or your competitors' software. Other users may be experts at using Windows, but may be new entrants to the industry in which your software is used.

One way of categorising the audience is by job role. For example, you might have:

This method of categorising the audience helps in two ways:

Task analysis

Different types of user perform different tasks. A task is a set of operations that is used to achieve a goal. A procedure is a list of instructions that tells one person how to perform a low-level task. A hierarchy of tasks exists, the lowest level of which is a set of procedures.

At higher levels, more than one person may perform a task. For example, a top-level task might be, 'perform annual stock-take'. This involves many people at many locations. At the lowest level, each procedure contains instructions for one person (although more than one person might perform the procedure).

To determine the tasks and procedures that people perform:

You should write one or more procedures for each person. Do not fall into the trap of writing a process (a description of how a system operates). Read more in this case study (www.techscribe.co.uk/techw/improving_user_instructions.htm).

Structure and content

A user guide deals mainly with work procedures. It tells people how to use the software to do a job. It answers the question, "how do I…?" Typically, this requires extensive reading and should be provided as paper documentation or in a printable format such as a PDF file.

A reference manual explains the features of a software product. Every dialog box, field, tab and button is explained. It answers the question, "what is x?" Reference material often can be provided successfully in electronic format only. Typically, you can provide it as context-sensitive online help. Each topic contains information about the specific fields on the dialog box from which the user called the help. You also need additional topics for reference material that does not relate to specific individual dialog boxes.

When you create a document, do one or more of the following:

What is the correct level of detail for the documents that you write? Put yourself in the position of your readers, and answer their questions. Focus on your core users. If most people are competent with using windows, write for them. In the introduction, state that you expect users to have basic ECDL, for example.

You are an expert who is familiar with the terminology (jargon), assumptions, and shortcuts in the subject area. Beware of making logical jumps that are not understood by non-experts. You may have to 'state the obvious', because to your intended audience, it may not be. On the other hand, don't be patronising. Brevity is a virtue. If a single sentence suffices, do not include a page full of screen shots.

Summary

You won't be able to please all the users all the time. However, with a careful evaluation of the typical users and the tasks they need to perform, you can create high-quality documentation that fulfils most users' needs. This in turn reduces your support costs and increases your reputation.

See also

How to write instructions

Usability, testing and documentation

Author training for software developers

Software Documentation, Ian Sommerville (www.literateprogramming.com/documentation.pdf)

This is a revised version of an article that originally appeared in the May/June 2005 issue of The Developers Magazine, the journal of The Developers Group (www.richplum.co.uk).

RSS feed