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:

Help the users of your software
Reduce 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 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:

Data entry clerk
Supervisor
Systems administrator
Help desk operator.

This method of categorising the audience helps in two ways:

It helps you to create documentation that is specific to the needs of each type of user.
The job roles indicate the skill level of users (for example, a systems administrator is an expert with using software in general, whereas a data entry clerk may be an expert or may be a novice).

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:

Observe users and talk to them about their jobs.
Extract information from existing documentation and from functional specifications.
Relate tasks to known practice. For example, if one task is to create a record, there should probably be tasks for selecting, modifying and deleting (or archiving) records.

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:

Split the document into sections based on roles, for example, 'data entry' and 'administration'.
Relate the procedures to tasks. Group similar tasks into the same chapter.
Organise chapters so that simple, common, and frequently performed tasks come before complex or infrequently used tasks.
If you need both task-based instructions and reference material, split the document into two major sections. The first section is a user guide. The second section is a reference manual. The user guide contains brief procedural information. It doesn't explain every field in every dialog box; rather, it contains cross-references to the reference section.

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.