7.1 Manuals

For many users, the manual is the most readily available source of information outside the on-line interface. For other users, the first place to go for information is the on- site support person or another, more expert user -- but those experts gained much of their knowledge from manuals. In general, a good manual is the most important extension to the on-line interface.

To help understand what a "good" manual is, it's useful to imagine doing a cognitive walkthrough on a manual and noting points where the manual could fail. First, the user may be looking for information that isn't in the manual. Second, the manual may contain the information but the user may not be able to find it. Third, the user may not be able to recognize or understand the information as presented.

A task-centered design of the manual can help overcome all of these problems. If you understand the user's tasks and the context in which they're performed, you'll be able to include the information the user will look for in the manual. This will be primarily task-oriented descriptions of how to use the system itself, but it may also include descriptions of how your system interacts with other software, or comments about operations users might want to perform that aren't yet supported. Knowledge of the users will help you present this information in terms that make sense to them, rather than in system-oriented terms that make sense to the software designers. To repeat one of Nielsen and Molich's heuristics, you should "speak the user's language."

The problem of users not being able to find information that's in the manual is probably the most difficult to address. Speaking the user's language will help some, and keeping the manual "lean," including only material that's relevant, will help even more. Indeed, brevity is the touchstone of an important approach to documentation, the "minimal manual," which we discuss under the heading of training. But the problem goes deeper than that, and we describe a further solution in the section on indexing.

Deciding on the top-level organization for your manual should be another place where the principles of task-centered design come into play. Using a manual is just like using the on- line interface: people can transfer the skills they already have to the system you're designing. When you're getting to know the users and their tasks, look at manuals they're comfortable with, and watch how those manuals are used. Make sure to look at the manuals users actually rely on, which are often task-oriented books written by third parties to fill the gaps left by inadequate system documentation. Design the manual for your system so it fits the patterns of seeking and using information that users find effective.

In the spirit of borrowing, the HyperTopic in this section shows a default manual organization that should be familiar to anyone who has worked with larger applications on personal or minicomputers. The manual has three parts. First, there's a section that describes common procedures in a narrative style. This section is organized around the user's tasks. Then there's a detailed description of each command, a section that's organized more in terms of the system. Finally there's a "Super Index," a section specifically designed to overcome the "can't find it" problem that users so often have with computer manuals. We might have also included a reference card, if users expected one. As a more convenient alternative, however, we'll assume that brief reference information is included as on-line help.

The next few paragraphs describe each of the sections in the default manual organization. Keep in mind that this organization wouldn't be appropriate for every system. It would be overkill for a VCR, for example. However, many of the principles that apply to the design, such as brevity and speaking the user's language, will apply to manuals of any size.