The Detailed Task Instructions give the user explicit, step- by-step instructions for performing each of the major tasks the interface supports. This section will support different needs for different users at different times. Some users will work through each step of each task in order to learn the system. More adventurous users may just glance through the Detailed Task Instructions to get an overview of how a task is performed, then investigate the system on their own, referring to the instructions only when problems arise. For both novices and experienced users, the section will be used as a reference throughout the useful life of the system.

Two questions to consider in writing the Detailed Task Instructions are what information the section should include and how that information should be organized. If you've been following the task-centered design process, the question of what to include should be easy to answer: The instructions should give step-by-step instructions for performing each of the representative tasks that have been the focus of the design effort. Additional tasks may be added if the representative tasks don't cover the entire system. Training for each task should cover everything a user needs to know for that task, with the exception of things that your intended user population already knows. The cognitive walkthrough will help uncover the details of what the user needs to know, and your early user analysis should describe the knowledge users already have.

The top-level outline of the Detailed Task Instructions section will simply be a list of the tasks. For each task, the instructions should give a brief conceptual overview of the task and the subprocedures used to accomplish it, then present sequential, step-by-step instructions for each subprocedure. The following example gives the overview for the mail-merge instructions of a word processor. That overview would be followed by the step-by-step details of each of the three major subprocedures needed to accomplish the task.

Example: Sample Overview Section of a Detailed Task Description

Section 3: Mail Merge

You can use the mail merge feature of UltraProgram to send identical or similar form letters to many addressees.

Imagine that you want to send a short letter to three customers, telling them that their account is overdue, by how many days. The detailed steps in this section show you how to:

     (1) create a file containing the basic letter,

     (2) create a file containing addresses and overdue information,

     (3) merge the two files to create the finished letters.

Notice that the sample overview is very, very brief. It's tempting to put a lot of detail into the overview, both to help the user understand the upcoming detailed steps and to call out useful options that the current task doesn't exercise. However, detail is exactly what the user does NOT need in the overview. If you fill the overview with technical terms and commentary on options, it will be meaningless techno-babble to the novice user. Even our simple mail merge overview won't mean much to a user who has never done something similar on another system. A novice's mental overview of an operation will slowly emerge out of an understanding of the details; the best your written overview can do is point them in the right direction.

The overview is also brief because the task itself is simple. If your representative tasks are complex, you should break them into simpler subtasks for the purpose of the manual. For example, don't give detailed instructions for doing a mail merge controlled by keyboard macros that load the files and insert today's date.

Another workable approach is to include a description of advanced options in a subsection at the end of the step-by- step task description. If you do this, be sure to put a pointer to that section into the overview, so users already familiar with similar systems can find it without working through details that don't interest them.

For each task, it's good to have a complete example, one involving actual file names, dialog box selections, etc. A more abstract description, such as, "Next, type in the file name," will inevitably leave some readers confused about the details abstracted. Showing the details of the example task will be much briefer and clearer than trying to explain the same information.

Within the step-by-step description of each task, the important principle is to be as brief as possible while still supplying the information the user needs. Remember that users already know some things, and the on-line interface provides additional information. Each step of the instructions should just fill in the gaps. Here again it's useful to think in cognitive walkthrough terms. Is the user trying to do the right thing? If it's not clear, the instructions should make it so. Is the action obviously available? If it isn't, the instructions should explain where it is. Will the user realize that the action moves them along the intended path? If not, clarify why it does. And finally, be sure to periodically describe feedback, so the user knows they're following the instructions correctly.

HyperTopic: Writing Tips for Manuals

Be brief. Briefness is central to a usable manual. In longer manuals, users often can't find the information they need because it's buried in a mass of irrelevant text. Here are a few suggestions on how to achieve briefness:

          o Write a section, then go back later and delete repetitive or unnecessary text.

          o Cut introductions, overviews, and summaries to the bone. Expert manual users often skip these sections, while novices just bog down in them.

          o Don't be historical. Users don't care about the design history.

          o Don't be philosophical. Users don't care about the design rationale.

          o Don't give technical details. Users don't care about the internal mechanisms.

          o Don't market. They've bought the product, don't try to sell them on it again.

Present an overview and a sequence of steps for each task. This is the approach we discuss in the text. Remember to keep the overview brief, and work through a simple but real task. A follow-up section on advanced features related to the task is optional.
Speak the user's language. You've heard this one before, but it bears repeating. You're writing a user manual, not a technical description for other software designers.
Find a light-handed editor. A good editor can catch awkward sentences and gaps in your presentation, as well as correcting errors in grammar and spelling that reduce the perceived quality of your product. A "light-handed" editor helps you maintain your personal writing style, which should reflect your knowledge of how users communicate.
Find an editor who is also a user. An editor who has a background similar to your user population can easily notice descriptions that are incomplete or hard to understand. An editor with no technical background will either limit the editing to simple grammar and spelling ("copy editing") or ask for too much additional detail in the descriptions.
Use a general and an internal style guide. A style guide gives answers to the hundreds of writing questions for which there is no "right" answer, such as whether to write "disks" or "diskettes," or whether to call your system "UltraProgram" or "the UltraProgram." A general style guide, such as the "Chicago Manual of Style," gives default answers to questions that commonly arise in books. An internal style guide is one you develop within your project or company, to cover points not in the general guide, as well as points where you want to disagree with the general guide. With an evolving internal style guide, you and your editor can make a decision on a style question once, then go on to more important things.
Use graphics sparingly and professionally. Except for screen dumps, graphics (cartoons, photos, abstract designs) usually don't add much to a manual. If you need an illustration, such as a drawing of hardware to show where switches are located, get a professional artist to do a clean, simple drawing.
Borrow an attractive and functional visual design. When you're deciding on the manual's visual design, such as the appearance of chapter headings, the font for the text, and the layout of tables, you should once again take a good look at several manuals that users find workable. You can also call in a professional designer to fine-tune things like type size and font; but borrowing from existing designs is the best way to start.