While professional technical writers are the ultimate address for producing an effective user manual, small developers often do not have the luxury of outsourcing the writing – initially, they must produce their own manual. Writing an effective user manual may look easy, but many developers discover that looks are deceptive – there is more to writing the manual than just listing features and step by step instructions. This short tutorial will give you the basics of creating a highly useable manual that will show off your product.

The First Principle: Organization
Most users turn to the manual when they need to perform some task. Usually, they have at least a vague idea of what they want to accomplish and they are looking for the correct feature to carry this out.

The first principle, then, in producing a useable manual is properly organizing the  information. The best manuals are organized around tasks that the user performs with the system. That is, instead of enumerating parts of the interface, or listing major concepts, the manual is divided into sections built around tasks and sub-tasks. Each major task or subtask should be a separate title whose significance the user can readily grasp. For example, titles should clearly state the task to be performed, like this:

Creating a Box Element

Linking Box Elements

Etc.

The titles should be arranged hierarchically so that users can easily find them in the table of contents. For example

Working with Box Elements
    Creating a Box Element
    Linking Box Elements
    Formatting Box Elements
Working with Arrow Elements

I suggest using a good outliner, such as Word’s outline feature, to rapidly organize titles and subtitles.

The Second Principle: Introductory Explanations
Many developers make the mistake of producing a bare bones manual of instructions with little explanatory content. While step by step instructions are important, good explanations of the feature that precede the instructions are just as important – sometimes even more so. That’s because users want to know a few things about the feature BEFORE they start using it:

• What’s its purpose? Is this really the feature that I need for what I want to accomplish?
• What is the result that I can expect after performing the feature?
• Are there any things to watch out for (pitfalls, unexpected or undesirable results, etc.)?
  

In addition, a really good manual provides examples of the results of performing an action so that the user gets an idea of what to expect. Not all features need this, but certainly the more complex ones do. In fact, for sophisticated users, a good example is often enough – they can usually skip the rest.

Explanations should directly address the user and should be written in a user friendly style:

“The XYZ enables you to …”

The Third Principle: A Good Overview
The showpiece of your manual is a comprehensive, but concise, Overview chapter. This should present the following:

• Major concepts on which the system is based. For example, a Project Planner might be based on the concepts of Time, Resources, and Costs – the Overview would discuss the relationship between these concepts, then briefly show how these are incorporated into the system. Examples and simple conceptual diagrams are important here.

• A brief “tour” of the system. This consists of a kind of demo in which you show just what the system can do. There are various forms that this can take – for some systems, an imaginary example can demo some of the more outstanding features; for others, you can provide a brief summary of the main features and what they are used for, along with sample results. This section of the Overview should have a lot of screen captures so that users understand the full power of the system and its capabilities.

By the time users finish reading the Overview, they should have a good idea of what the system can do, and what features are relevant for their needs. Don’t clutter the Overview with operating instructions or technical details – these should be left for the rest of the manual.

The Fourth Principle: Clear Operating Instructions
Operating instructions are the heart of the matter. Keep these rules in mind:

• Begin each operation with a “to” statement that clearly defines the task to be performed:

        “To start the microwave:”
        “To print a document:”
        Etc.

• Procedures of more than one step should be numbered.

• Conditions, locations of buttons, menus, etc. should be stated first, i.e.:

        “On the File menu, choose Open.”

• Capitalize the names of all menus, dialog boxes, buttons, etc. And make sure that you use their names in the instructions!

• Keep the results of an action in the same step as the action itself – this makes it easy for the reader to understand what happens after performing something.

• Include screen captures where appropriate (for major steps).

If you have instructions that are longer than 8 steps, you might have to reformulate your “to” statement as the task may have to be divided into two or more stages. Do not force the user to follow a very long sequence of instructions.