On writing documentation and how this has become a lost art, Paolo Amororso’s toot brough to my attention a wonderful article publised in Byte Magazine 1983/05 by Dana Sohr.

For reading easiness I reproduce the text here:

Better Software Manuals

Your company’s survival may depend on them.

By Dana Sohr, POB 953, Beltsville, MD 20705

Incomplete, disorganized, and unreadable — that’s the way to describe many of today’s software manuals. And indeed, what other reaction could there be to the following:

• a 79-page software manual that on page 69 describes “the first thing you will have to do before performing anything …”

• a manual that claims the user doesn’t need to read other manuals, then, three pages later, refers the user to another manual for necessary information.

• a manual containing sentences such as: “The insert/delete key deletes characters to the left of the cursor position if operated in lowercase and if the Shift key is held down at the same time as pressing INST /DEL all characters to the right of the screen cursor are moved one position to the right with every keystroke and spaces created.” (This manual, believe it or not, supports a $500 program.)

Purchasing decisions
will be made not so
much on program
features but on how
easy programs are to
learn and use.

You don’t have to look very far to find such examples, and you don’t have to listen very long to hear complaints. Software manuals today are like the bicycle-assembly instructions of yesterday — those notorious documents responsible for unassembled bicycles left rusting away in basements everywhere.

Let’s face it: many software manuals are patchwork affairs thrown together at the last minute either by programmers or by technical writers who write too technically. Both assume that the user, given a few scraps of information, can figure out the rest.

This approach certainly saves time and money, but in the long run it is economic suicide. With more computer novices entering the software market, and with similar programs competing for everyone’s attention, purchasing decisions will be made not so much on program features but on how easy programs are to learn and use. Thus, purchasing decisions will increasingly be made on the strengths and weaknesses of manuals.

Imagine this scenario: a hardware store owner is shopping for a computer. He’s attracted to the Apple II because he’s learned that the Apple can run software to write invoices. But lo and behold, the local computer store stocks five invoicing programs for the Apple — programs that just aren’t all that different.

Which program does he buy? He looks at the documentation, and he buys the program that has the most attractive, readable, and understandable manual.

Buyers are discriminating. In the future, when there will be more competing products from which to choose, buyers can afford to be even more discriminating. They will buy from anyone who can give them readable, usable manuals.

The same thinking also applies to computer-store owners. Why should store owners bother to sell a program with a shoddy manual when they can sell a competing program with a good manual? If they sell the first program, they know they will receive follow-up phone calls from frustrated customers and may even have to conduct instore training sessions. But if they sell the competing program with the good manual, the store owners will spend much less time supporting the program; they’ll receive fewer phone calls and answer fewer questions. For computer-store owners, it’s more profitable to sell those programs backed by good manuals.

Good software manuals require an investment of time and money. Once that hurdle is crossed, producing a solid manual is a matter of knowing who the user is, how the user learns, what he needs to learn, and how to evaluate the finished product. This article offers advice to vendors and writers. It is designed to prevent the question, “How does this software work, anyway? I couldn’t understand the manual.”

A manual transmits information. Unfortunately, the transmission has to overcome some big obstacles before reaching its audience, the user. The biggest obstacle is the user himself.

Create the Right Tone

Many will agree that first impressions are lasting ones, and the user’s first impressions of your manual are crucial. If your manual is sloppily packaged and typographically ugly, or if it appears to be a well-packaged piece of technical drudgery, you are working at a serious disadvantage. You aren’t trusted, you aren’t liked, and any information you attempt to transmit will be distorted. Create the right tone, and what you transmit will be received.

Define Your Audience

To create the right tone, think of the user, then tell that user what he wants to hear. If the program handles accounts receivable, tell the user how quickly and accurately he can send out his bills. Then tell him how easy the program is to learn and use. If the program does payroll, tell the user how quickly and accurately he can print checks. Then tell him how easy the program is to learn and use.

Entice and assuage the user by giving him what he wants, then go on with the business of listing necessary equipment, describing specific features, and detailing how to go about using the program.

Your target audience will determine whether you transmit information at a breakneck speed or parcel it in doses. Study your intended users, and ask yourself some questions. What does the program do? Does it compile BASIC code, or does it teach BASIC? Different programs mean different users. The user of the first program, who is already writing his own code, understands something about programming. The user of the second program, who would like to write his own code, understands far less.

A manual for the experienced user should transmit information at a faster pace than does the manual for the novice. (For example, the first manual should not stop along the way to explain variable arrays; the second manual should.) By making educated guesses about the intended users of a program, you can determine what information the manual should transmit, and at what pace it should be transmitted.

In tutorials for novices, tone and pacing are crucial. Novices are bound to be shy about using a computer, and in some cases they will be terrified. Remember, many computer users today do not voluntarily decide to work with a computer; the decision is made for them by their managers. A manual for these novices must do several things. It must soothe fears (“You can’t hurt the computer, and the computer can’t hurt you”); it must motivate (“The computer does the mindless tasks you always hated to do”). Only after you’ve created the right tone should your manual go on to provide well-paced, step-by-step knowledge.

Often you can’t classify the typical user of a program. For example, both novices and seasoned computer users buy word-processing programs. In this case your word-processor manual should cater to the novice. The manual will not neglect the experienced user because all the information is provided, just at a slow pace. The experienced user knows how to use the keyboard, how to control the cursor, and how to protect disks; he can bypass such instructions and get to information he hasn’t encountered before. Rather than resent the manual for slowing him down slightly, he’ll probably wish that when he was a computer novice such a manual was the rule, not the exception.

Now that you know who the user is, how to create the right tone, and how to pace the manual, think about how to transmit information in a way that makes learning easy. After all, the user might be receptive to new information, but the information serves no purpose unless he can understand and recall it. Learning hinges on the way information is organized and the way it’s presented.

Organize by Tasks

No matter who the intended user is, a manual should be task-oriented — organized according to the tasks the program performs.

Although software manuals are, as a group, moving toward this orientation, a large number retain a more primitive organization. Many manuals are option-oriented; they begin with a section on the program’s first menu option, then proceed to a section on menu option 2, and so on. That’s fine — unless the user cannot perform the options in numerical order.

Consider chapter 1 of a certain bookkeeping-program manual. This chapter describes how to prepare invoices because “Invoices” is listed as menu option 1. In chapter 13, the user is instructed on recording customers’ names and addresses because “Customers” is listed as menu option 13. Unfortunately, until the user records his customer information (chapter 13), the program won’t let him prepare invoices (chapter 1). So the user must read all the way to chapter 13 before actually doing work with the program. And after getting to chapter 13 and recording customers, the user must then try to figure out what to do next. Can he now go back to chapter 1 and prepare some invoices, or does he have to do something else first? The manual doesn’t help him at all.

Learning hinges on
two basic factors:
the organization
and presentation
of information.

An option-oriented manual doesn’t synthesize information; it dumps it in the quickest (and cheapest) way possible. The user must read every chapter at one sitting, then try to arrange the information into some sort of logical order.

This scheme of manual organization makes great sense to the programmer, who organizes a task by breaking it into discrete sections of code, but it makes no sense to the user, who needs to be told what tasks to do and when to do them. For example, a word-processor manual should not begin with instructions on creating disk files because the program can’t be used that way. Instead, the manual should first tell the user about editing and formatting, then tell him how to save material.

Task-orientation is no great mystery. Before you begin writing your manual, analyze the various tasks the program performs, then describe those tasks in the order in which the user should perform them. Make sure that all information needed to do the tasks is provided and that extraneous information isn’t included. Most users don’t care how a program works; they just want to know how to use it.

Organizers

The manual shouldn’t joggle the user with unexpected material because the user won’t understand it fully. And if he doesn’t understand it, he certainly won’t be able to recall it.

To prepare the user for new information, include organizers in your text. The organizer, a very simple tool, can be a short introduction to a new section or chapter. An organizer for chapter 2 of a word-processor manual might look like this:

In chapter 1 you learned how to format and edit what you type. In this chapter you will learn how to save what you type. Saving text on the disk will create a “disk file.” Think of a disk file just as you would think of a file in a file cabinet. You can look at a disk file at any time, just as you can look at a file in the file cabinet. You can also add things to the disk file, change the file, or throw the file away…

With this organizer in mind, the user can easily understand the purposes of the SAVE, REPLACE, and ERASE commands.

As the example shows, the organizers should look backward and forward at the same time. They should tell the user where he’s been, where he is, and where he’s going. A new computer program is a strange land in which the user can easily get lost. If the manual provides organizers, the user is always on solid, familiar ground. If organizers aren’t provided, the user wanders aimlessly. He’s never certain where he is, and the little that he learns is gained by trial and error.

Move from the Whole to the Parts

Organizers alone don’t ensure that the user will understand and recall new information. The manual should also move from the whole to the parts. At the same time, new information should be linked to knowledge the user already has.

Consider a wholesaler who buys an accounts receivable program. Like most software, this program was purchased because it makes a particular task easier to do; the wholesaler already knows a lot about that task before he lays his hands on the manual. He already knows, for instance, how to prepare an invoice. He knows that the invoice should include the customer’s name and address, inventory codes, prices, and so forth. He also knows that, according to his usual method, after preparing an invoice he must manually adjust customer accounts, tax accounts, salesman accounts, and so on.

However, while he knows how to prepare an invoice by hand, his new program does it differently. And the manual can use these differences to its own advantage.

People learn partly by contrast; new information isn’t understood until a person compares it to a pattern created by older knowledge. For example, the statement “red is a bright color” can be understood only by mentally comparing red to other colors. Likewise, the wholesaler won’t understand his accounts receivable program until he compares it to what he already knows. The manual should make that connection for him. It should briefly summarize how invoices are prepared by hand, then summarize how the program prepares invoices. This links new information to old knowledge, creating a clear contrast from which the wholesaler learns. “In the old days,” he thinks, “I had to do all this stuff by hand. Now, after I prepare an invoice, the program automatically adjusts my customer, tax, and salesman accounts.”

By starting at a simple whole and by linking new information to old knowledge, the manual gives the user his bearings. Now it can safely move on to the separate parts of the task and present step-by-step detail on preparing invoices.

Repeat, Repeat

Sure, the user is intelligent; he bought your software, didn’t he? But don’t assume that he will instantly grasp important points. You have to repeat those points several times, then mention them once more in summary passages.

I’m not advocating that manuals be written for the addled. What I am arguing is that learning a new program is not unlike being in third grade and learning multiplication.

Remember third grade? How many hot afternoons did you spend at the flash cards until you could remember that 9 times 9 equals 81?

Because manuals should move from simple to complex information, it’s critical that you make sure the user is with you every step of the way. This means that every important piece of information should be highlighted and dwelled upon, then drilled into the user’s head. You can do this subtly, by providing several examples of a feature new to the user. Or you can do it directly, by repeating a definition. In a word-processor manual, for example, the user could be told several times the purpose of a command: “Remember, when you use the REPLACE command, the file you were working on replaces the old version of the file.” Using this direct repetition, you run the risk of irritating those users who understood the REPLACE command immediately. But if you skim over important points, you run the risk of frustrating many users.

By orienting the manual around the tasks that must be performed, by providing organizers, by linking new information to old knowledge, and by repeating important information, you take a long step toward ensuring that the user can understand and recall new information. But that’s only half the story. You also must present information in a way that helps users learn.

Write Actively and Logically

When you prepare a software manual, you serve as a teacher. Unfortunately, you can’t communicate verbally with the user. You can’t shout and wave your arms and prod the user awake. You don’t even know when the user’s attention is lagging. However, if you write to engage the user at all times, presenting your material in a warm and lively style, you stand a good chance of communicating effectively. Dry, passive, turgid writing is not only boring, it hinders communication.

Use active verbs. A passive sentence such as, “The program was bought by Mary,” takes about 25 percent longer to comprehend than the sentence, “Mary bought the program.” Moreover, the second sentence, because it is more vigorous than the first, is easier to remember.

Arrange instructions in correct sequence because that’s how the user should perform the instructions. If you give the instruction, “press the Y key while holding down the Shift key,” the user will probably press the ‘x’ key, then the Shift key, and discover that nothing happens. Change the instruction to, “hold down the Shift key, then press the Y key.”

Illogical instructions disrupt and sometimes destroy your message. You should also avoid pointless redundancy (e.g., “a total of four disks”), inconsistency (a command is first “SAVE” then “Save”), pretentiousness (using “determine” where “check” would do), and vagueness (“enter the file name”).

Write Relevantly and Simply

Make your writing more personal, more relevant to the user. Use the pronoun “you,” not “we,” as the former is more relevant to the user. Use the present tense; again, it is more relevant to the user.

Make the manual human. Use humor. Use familiar, everyday examples and analogies. Use hypothetical characters. Talk to your reader, don’t just write at him.

Such techniques are, unfortunately, considered to be the tools of novelists alone. What the manual writer often forgets is that he, too, must serve his audience. He must instruct the user, but that’s impossible when the user is bored and frustrated. Literary techniques applied with discretion keep the user interested and receptive.

Write as simply as you can. Avoid abstract nouns and verbs (e.g., concept, conceptualize). Abstractions do nothing but disrupt your efforts to teach the user. Above all, don’t use jargon unless it’s necessary and unless you’re willing to define it the first few times you use it.

Use artwork wherever possible. Photographs and illustrations break up large bodies of type, attract the user’s attention, and make information more relevant. Instead of simply describing how to load disks, include an illustration. Rather than just describing an important screen image, include a photograph.

Evaluate with the Eyes of a User

The evaluation is the last line of defense against errors, but too often vendors and writers ignore it (judging by their final products).

The evaluation doesn’t have to cost a lot of money, and what money is spent comes back in the form of customer loyalty, goodwill, and sales. During the evaluation, you should identify and correct the manual’s shortcomings; errors should be removed and omissions filled in. A critical evaluation produces a wellwritten, truly instructive manual that will make friends of users and computer-store owners alike.

You can evaluate the final draft of a software manual in various ways. Some methods cost more than others, and some are more effective than others, but no single method is sufficient. A thorough evaluation will incorporate two or more of the following methods:

Editing: Hire a professional editor on a temporary basis, preferably an editor experienced with instructional materials. An experienced editor can read the manual as the user would, and he can correct writing deficiencies.

Checklist: The checklist, a very simple method of evaluation, sets standards for what the manual should provide. Here’s an example of a much simplified checklist:

• Does the manual include (1) a table of contents, (2) an index, (3) introductory and summary material for each section and chapter, (4) a tutorial section in which the user gains hands-on experience with the program’s functions, and (5) a quick reference section in which the user can find information quickly and easily?

• Is the manual task-oriented?

• Does the manual move from the whole (a nontechnical overview) to the parts (step-by-step knowledge)?

• Does the manual tell the user how to recover from errors, and are all error messages listed and explained in a section where the user can find them easily?

• Do section headings give a good idea of what the sections contain?

To devise a thorough checklist, examine existing manuals. What mistakes did you make in the past? What did you omit? Why did users complain?

Devising a checklist takes time, care, and effort. Fortunately, it can be used to evaluate future manuals, too. But the checklist alone is not a thorough method of evaluation. It uncovers mechanical errors but cannot uncover missing or ambiguously worded instructions.

Self-Review: Self-review, like the checklist, is a simple method of evaluation. The manual writer tests to see if he can use the program based only on the manual’s instructions. In the process he typically uncovers missing or ambiguous instructions, incomplete descriptions, misspellings, and grammatical errors.

Self-review should be used for every manual but not as the sole method of evaluation. The writer, if he has any ego at all, isn’t objective about his writing; he likes what he has written. Further, he already knows how to use the program, and during the self-review he may unconsciously supply information that is missing from the manual.

Programmer Review: Have the programmer review the manual. The programmer checks to see that the manual has covered all the program’s functions and that it has covered them correctly. Unfortunately, while the programmer is the person best qualified to evaluate the technical accuracy of the manual, he will probably be of less help in evaluating the manual’s organization and presentation.

User Walk-through: Select potential users of the program, hand them the manual, and see how quickly they learn the program. (Select worst-case users — people who have no computer experience.) Are they confused and frustrated by certain sections of the manual? Do they have trouble finding information they need? Revise the sections where users run into trouble. Include more introductory and summary material, provide more examples; provide whatever the users believe is lacking. Then repeat the process with another group.

• Users, after reading the manual, can be formally tested on their proficiency with the program. Can they perform all of the program’s functions? How long does it take them? If a large percentage can’t perform a certain function, revise the sections where that function is covered.

Users will often respond in mysterious ways to instructions that seemed perfectly clear to the writer. Those instructions can easily be revised. Users also uncover missing instructions and incomplete descriptions better than the writer or programmer can.

Field Test: If you’re willing to spend some time and money, conduct a formal field test of both the program and the manual. Install the program at several sites, provide drafts of the manual, and then wait for the phone to ring. Are the test users calling you day and night? Can they understand the manual? Can they use the program? It costs less to answer these questions now, when only a few people are trying to use the program, than when 1000 buyers are calling in for help.

After two weeks, ask the users for comments and suggestions. Accept criticism, then use it to improve the manual. As in the user-walk-through method described above, test the users for specific knowledge, then revise the sections that don’t seem to be communicating effectively.

Conclusions

Buyers want and expect good manuals, and they will buy from anyone who can provide them. Thus, the poor quality of many of today’s manuals offers a tremendous opportunity to enterprising vendors. Those who make a serious effort to produce well-written, instructive manuals will have a big advantage over their competitors; those who do not make the effort will eventually fall by the wayside.

In all things — preparation, organization, presentation, and evaluation — all decisions hinge on the user — who he is, what he knows, and how he learns. If you constantly keep the user in mind, you’re on your way to producing a readable, usable software manual.

Bibliography

1. Al-Awar, J., A. Chapanis, and W. R. Ford, “Tutorials for the First-Time Computer User,” IEEE Transactions on Professional Communication, vol. PC-24, 1981, pp. 30-37.
2. Brett, C. E., “Six Keys to Better Technical Writing,” Journal of Technical Writing and Communication, vol. 1, 1971, pp. 45-59.
3. Coney, M. B., “The Use of the Reader in Technical Writing,” Journal of Technical Writing and Communication, vol. 8, 1978, pp. 97-105.
4. Douglas, G. H., “The Common Diseases of Technical Writing,” Journal of Technical Writing and Communication, vol. 4, 1974, pp. 37-46.
5. Goldfarb, S. M., “Writing Policies and Procedures Manuals,” Journal of Systems Management, vol. 32, 1981, pp. 10-12.
6. Haupt, M., P. Perryman, and C. R. Schanstra, “Documentation Is the Key to Productive Computer Use,” Information and Records Management, May 1982, pp. 22-28.
7. Maynard, J., “A User-Driven Approach to Better User Manuals,” Computer, January 1979, pp. 72-75.
8. McCaskey, D. S., “Technical Writing: The Importance of Reader Interest,” Journal of Technical Writing and Communication, vol. 3, 1973, pp. 217-221.
9. Meredith, G. P., “The Flow of Information,” Occupational Psychology, vol. 31, 1957, pp. 99-103.
10. Vandenburg, J. D., “Improved Operating Procedures Manuals,” Ergonomics, vol. 10, 1967, pp. 214-220.
11. Vaughn, J., “A Prescription for Programming^ Least Popular Phase,” Datamation, vol. 25, January 1979, pp. 185-186.
12. Wagner, C. B., “Quality Control Methods for IBM Computer Manuals,” Journal of Technical Writing and Communication, vol. 10, 1980, pp. 93-102.
13. Wiedman, T. G. and F. H. Ireland, “A New Look at Procedures Manuals,” Human Factors, vol. 7, 1980, pp. 371-378.
14. Whittaker, D.A., “Write for Your Reader,” IEEE Transactions on Professional Communication, vol. PC-23, 1980, pp. 170-173.

About the Author

Dana Sohr is a freelance technical writer and editor. He writes a column on computers for a national trade magazine and is a consultant on office computers for the newspaper industry. His recent work includes a manual for LITMAS ’ (a cross-indexing program for the Apple 11) and one for Calc Result (a spreadsheet program for the Commodore 64).

Acknowledgment

This article was prepared as part of a research project done in conjunction with Ben Shneiderman of the University of Maryland Computer Science department. Sincere thanks go to Dr. Shneiderman for his advice and ingenuity.