Following the principles of recognizable structure and user orientation, what are some ways to organize a technical document? The following types of organization are familiar to most readers, and therefore fulfill the first principle—recognizable structure. Each will be “user oriented,” however, only if it is the best type of organization to meet the user’s specific needs:
Chronological Events are described in the order in which they occur.
Known-to-Unknown Information builds from familiar, simpler (or Simple-to-Complex) to less familiar, more complex concepts.
Question-and-Answer Information anticipates the user’s ques- tions and provides answers.
Alphabetical Information is tied to terms that can be alphabetized.
Task-Oriented Information and instructions are orga- nized in the order in which the reader customarily does her job.
Most technical documents don’t purely follow any single organizational type. Documents tend to combine an overall order (for example, a chrono- logical order) with different kinds of organization within their sections.
The book you are now reading is chronologically organized to match the steps in a beginning technical writer’s career. It’s meant to be read
11
through first, then used for reference later. Chronological order works best for books that lead readers through a sequence of steps and for books that will be read from start to finish.
Information organized from known-to-unknown (or simple-to-com- plex) is common for a tutorial or any teaching text. It begins with what the user knows and proceeds to teach new concepts based on familiar ones.
Troubleshooting material frequently follows question-and-answer order. Online FAQs (Frequently Asked Questions) are another example of this order. This “order,” however, does no more than put a question before its answer. You therefore need to organize questions and answers further, either by need (most frequently asked questions first) or by diffi- culty (simple-to-complex).
Common examples of alphabetical material include glossaries and bibliographies. Reference material that describes computer commands is often ordered alphabetically.
Task-oriented documents provide information about tasks, usually in the form of instructions, in the order in which the reader performs them. Studies have revealed that of all the reading people do on jobs, only 15 percent is reading to learn—that is, to retain information. The rest is reading to do1—that is, to complete a task or procedure. Writing for the
doer requires task orientation. Rather than focusing on the features of a product, you direct the actions the reader performs. When the reader completes a task, he or she puts the manual away—or exits the online instructions—and can even forget the documented information.
Says R. John Brockmann in Writing Better Computer User Docu- mentation:
Readers only use documentation to get their job completed. . . . Docu- mentation is only a tool and not an end in itself. Thus, the best design for software documentation is one that fits the reader’s method of work- ing and requires the least attention and learning. This self-effacing design for documentation is where we need to begin, and this type of design is called task orientation.2
How does task orientation dictate document organization? A great example on my shelf is an old manual for consumer accounting software. The product allows users to track and balance their various accounts, including checking, credit cards, mortgage debt, and so on. Unlike pro- fessional accounting programs, this software is geared to the layperson, and the manual guides the user through tasks she would normally per- form, in the order and language she would use. The first few chapters are listed below:
• Opening your first account • Using the register
• Writing checks • Printing checks
• Reconciling your records
Research has shown that while task-oriented documents take 42 per- cent more time to create than product-oriented documents, they increase user productivity by 41 percent. Also, users are happier with them—79 percent of those who were asked to compare the two preferred the task- oriented documents.3
One more way of ordering information—by need—requires men- tioning here because it can be useful for some documents. Ordering by need means placing frequently required information before information the user needs less frequently. This order can defy the reader’s expecta- tions. For example, most experienced readers of technical documents expect installation instructions to appear before reference information, even though reference information is needed more frequently than instal- lation instructions. If you place reference first and installation last, users will find the organization confusing.
However, most sales or marketing-related documents—including most Web sites—benefit from being organized by need because the reader is there by choice. If you don’t provide what the reader most needs up front, you will lose him!
No matter how logical a structure seems, it won’t work well unless users can find their way in it. In a manual organized by need, you will have to provide excellent reference aids, because the manual structure is less readily recognizable to readers than some other structures. Later in this chapter, you’ll learn how to use a “road map” to clarify this type of document organization.