How to write user documentation

In many software companies, software developers write documentation for users. If you must write a user guide, a reference manual, or online help, where do you start? This article gives you guidance.

The business case

Typical reasons for creating user documentation are shown below:

Before you start to create the documentation, identify the reasons for creating the documentation. If documentation will not improve profits, do not create documentation. For example, possibly it is cost-effective to answer more telephone calls to your service desk instead of supplying detailed documentation. (Possibly, you must supply documentation for regulatory or legal requirements. Therefore, ask your legal team.)

Do not create documentation to explain a clunky product. Instead, change the interface. I showed a company how to decrease 14 installation screens to only one screen. The software developers did not see what was clear to an outsider. Therefore, get help from a professional usability expert.

Audience analysis

Documentation has no use if it does not answer the questions that people ask. Therefore, before you start to write, you need to know about the audience and the tasks that they do.

Possibly, some users know Windows and are subject-matter experts, but they have never used your software or your competitors' software. Possibly, other users are experts with Windows, but they are new to the industry in which your software is used.

One way to categorize the audience is by job role. For example:

This method of categorizing the audience helps in two ways:

Task analysis

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

Possibly, at higher levels, more than one person does a task. For example, a top-level task is 'do annual stock-take'. The task involves many people at many locations. At the lowest level, each procedure contains instructions for one person. (Possibly, more than one person does the same procedure.)

To find the tasks and the procedures that people do:

Write one or more procedures for each person. Do not write a process. Read more in 'Case study: improving instructions'.

Structure and content

A user guide is primarily about work procedures. A user guide tells people how to use software to do a job. A user guide answers the question, "how do I…?" If there is much conceptual information to read, supply a user guide as printed documentation or in a printable format such as a PDF file.

A reference manual explains the features of a software product. Each dialog box, field, tab, and button is explained. A reference manual answers the question, "what is x?" Sometimes, reference material can be supplied successfully in electronic format only. Typically, you can supply a reference manual as context-sensitive online help. Each topic contains information about the fields on the dialog box from which the user called the help. You also need topics for reference material that is not about particular dialog boxes.

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

To find the correct level of detail for a document, put yourself in the position of the readers, and answer their questions. Focus on the primary users. If most people know how to use Windows, write for them. For example, in the introduction, write that you expect users to have basic ECDL.

You are an expert who knows the terms, the assumptions, and the shortcuts in the subject area. Do not make logical jumps that non-experts do not understand. Possibly, you must 'state the obvious', because the audience does not know the subject. However, do not give information that is not necessary. If one sentence is sufficient, do not include a page of screen shots.

Summary

You cannot please all the users all the time. However, with a careful evaluation of the typical users and the tasks that they do, you can create excellent documentation that helps most users. This documentation will decrease your support costs and increase your reputation.

See also

How to write instructions

Usability, testing, and documentation

Technical author training for software developers

Documentation review

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

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

RSS feed