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:

To help the users of your software.
To decrease your support costs.
To use as a marketing tool.
To improve your company's image.

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 not 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:

Data entry clerk
Supervisor
System administrator
Service desk operator.

This method of categorizing the audience helps in two ways:

This method helps you to create documentation that is applicable to the needs of each type of user.
The job roles show the skill level of users. For example, a system administrator is usually an expert with software, but a data entry clerk can be an expert or a novice.

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 includes 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:

Observe users and speak to them about their jobs.
Get information from documentation and from functional specifications.
Match the tasks to known practice. For example, if one task is to create a record, other tasks are necessary to select, change, and delete (or archive) records.

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 satisfactorily 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:

Divide the document into sections for each role, for example, 'data entry' and 'administration'.
Match the procedures to tasks. Group similar tasks into the same chapter.
Organize chapters so that frequent tasks come before infrequent tasks.
If you need both task-based instructions and reference material, divide the document into two sections. The first section is a user guide. The second section is a reference manual. The user guide contains short procedural information. It does not explain each field in each dialog box. Instead, it contains cross-references to the reference section.

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 screenshots.

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.