How to write user documentation

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

The business case

Typical reasons for producing user documentation are to:

Help the users of your software
Decrease your support costs
Use as a marketing tool
Improve your company's image.

Before you start to produce the documentation, identify the reasons for producing it. If documentation will not improve profits, do not produce it. 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 produce documentation to explain a clunky product. Instead, change the interface. Once, I showed a company how to decrease installation process from 14 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 Microsoft Windows and are subject matter experts in their field, but they have never used your software or your competitors' software. Possibly, other users are experts with Microsoft Windows, but they are new to the industry in which your software is used.

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

Data entry clerk
Supervisor
System administrator
Service desk operator.

This method of categorising the audience helps in two ways:

It 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 either 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 a 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:

Observe users and talk to them about their jobs.
Get information from existing 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 (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 is primarily about work procedures. It tells people how to use the 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 particular 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 based on roles, for example, 'data entry' and 'administration'.
Match the procedures to tasks. Group similar tasks into the same chapter.
Organise 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 Microsoft 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 (jargon), assumptions, and 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 a single 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 high-quality documentation that fulfils most users' requirements. This high-quality documentation will decrease your support costs and increase your reputation.