Structuring Your User Documentation to Improve Usability

In the first article, I described some areas that need to be considered when planning to write computer documentation (or any other type of documentation). Now that you have explored all of those issues and know your audience and its needs, you can begin to think about the document design.

The term design refers, in part, to the overall structure of the document. You should design the structure of the documentation before you begin to write. All user manuals should have a table of contents and manuals of any length should also include an index. Remember that our goal is to create information that is easy to read, understand, and access. The table of contents and index are critical to the issue of accessibility. A helpful table of contents will concisely describe the major topics covered without using jargon or cryptic abbreviations.

You should develop the index with great care. We have all had occasion to search a document for information, only to find frustration because the index was not sufficiently detailed, or did not exist at all. If you are writing documentation for a commercial product, you would be well advised to employ a professional indexer. Yes, there are people who specialize in creating document indexes. These specialists are best equipped to generate an index that aids users in finding the information they need. They carefully analyze the information contained in the document to decide what words (including synonyms) and phrases a user would be likely to seek.

In addition to the table of contents and index, the document design should include decisions on how to organize the information. You need to decide whether an alphabetical or a functional breakdown would best achieve your goals. An alphabetical listing of each function along with an explanation of its use is commonly used in a reference manual. Such manuals can be helpful to experienced users of your system, but they may not help the novice.

You may organize a functional approach in any number of ways depending on how you think a user will want to access the information. Sometimes, a "how to" or task-oriented approach is effective. This type of document may be the best when you know your users will want to know how to perform a specific set of functions. For example, when setting up an electronic fax system, we knew that the users would need to know how to: send a fax, track the status of a fax, set up a phone list, and set up group lists (to send a fax automatically to a specific list of people). We designed the documentation, therefore, to explain each function in a separate section entitled, "How to Send a Fax," etc.

For products that can be used in many different ways, such as a word processor, this "how to" approach may not be appropriate. This situation may require the creation of more than one manual. For example, WordPerfect® for Windows 6.0 came with several manuals. One is a reference manual that has a short introductory section that gives me installation instructions, customer service phone numbers, and some basic tips for using WordPerfect. The remainder of the manual is an alphabetical listing of the software's features with an explanation of how to use them. A detailed index is included at the end. A second very thin booklet also gives the installation instructions and briefly outlines new features and ideas for creating documents. The third manual helps a new user learn about the product by offering a series of lessons that starts with the basic steps for creating and editing a document and then builds up to the more advanced functions. Two additional guides describe how to use templates and the drawing function.

These days, most products come with less printed material and more online documentation. Online documentation can also take several forms: conceptual help, procedural help, tutorials, troubleshooting information, and more. Online help comes in many flavors today: Windows help file, HTML, HTMLHelp, or Java help. Again, you need to assess your users’ needs and design help that provides the information they need in a form they can use.

These examples of documentation types are intended to get you thinking about how you can approach the situations you encounter. For a narrowly defined audience with a finite set of functions to perform, the task-oriented method may be best. When you have a much broader and diverse audience and set of functions, you may need to devise a series of manuals and online help to meet the diversity of needs.