In preparing these notes I consulted dozens of software engineering texts. One thing is clear, there is very little written on writing user's manuals. One wonders why when you consider there are so many computer manuals of such low quality. I suspect that professors as well as programmers don't like writing them!

As with any writing, the author of a user's manual must consider his/her audience and purpose carefully.

I. Audience: Who is the intented audience?

A PC computer user; a manager; a programmer; an UNIX guru? Each of these individuals will want a very different manual.

II. Purpose: What is the purpose of the manual?

Some possible purposes:

"One common source of frustration is the user's manual. Too frequently our software designs expect the poor user to live with a thick manual. The user is frustrated at having to refer to the manual in the first place, frustrated because the manual can't be found, and finally frustrated because the information can't be found in the manual. I view a manual as a software designer's list of failures." [He is discussing interactive personal computer software here. DCH]

"Ideally a software product should be obvious to use: where it isn't obvious, the designer should provide helpful information and eliminate the need for a manual. Someday we should be able to realize this ideal, and our software will require as much preparation as watching television does. Today, however, most programs are more like Verdi operas; they communicate in a foreign language [Italian] and require reading notes in advance to have any idea of what is happening. Of course, if done with the genius of Verdi, our programs might attract a devoted following across cultures, but they will appeal to the masses only in a culture that understands the language." [page 63 in reference 4].

Assuming we are not geniuses like Verdi, we need to write high quality manuals. What sections should we include?

III. Sections in a User's Manual:

Richard Fairley [1] in his textbook on software engineering gives the following outline:

"Table 2.7 Outline of the User's Manual
Section 1: Introduction

Robert Glass [2] supplies outlines for user's manuals from two industry wide standards - The National Bureau of Standards (NBS) and The U. S. A. Department of Defence (DOD) See page 121 in reference 2.

Below is what I think should be in a user's manual:
1. Title Page

IV. Physical Appearance:

On style of computer manuals we listen to the main character of Zen and the Art of Motorcycle Maintenance [5] say:

"While at work I was thinking about this same lack of care in the digital computer manuals I was editing. Writing and editing technical manuals is what I do for a living the other eleven months of the year and I knew they were full of errors, ambiguities, omissions and information so completely screwed up you had to read them six times to make any sense out of them. But what struck me for the first time was the agreement of these manuals with the spectator attitude I had seen in the [motorcycle] shop. These were spectator manuals. It was built into the format of them. Implicit in every line is the idea that "Here is the machine, isolated in time and space from everything else in the universe. It has no relationship to you, you have no relationship to it, other than to turn certain switches, maintain voltage levels, check for error conditions . . ." and so on." [page 26 in reference 5]

"The first thing to be observed about this description [manual] is so obvious you have to hold it down or it will drown out every other observation. This is: It is just duller than ditchwater. Yah-da, yah-da, yah-da, ya ..." [page 71 in reference 5]

" .. . the observer is missing." [page 71] [He advocates that computer manuals be written not where the user is an observer but where the user participates in the activity.]

How do we write manuals that are not ditchwater dull? Glass says to use "a lively writing style" [page 121 in reference 2].

1. Fairley, Richard, Software Engineering Concepts, McGraw-Hill, 1985.
[Excellent software engineering text. Worth buying if you plan to work in industry. Lots on documentation but only a little on user manuals.]

2. Glass, Robert L., Software Communication Skills, Prentice Hall, 1988.
[Best book on software documentation. Every programmer should own a copy. Extensive appendices on DOD documentation standards. Pages 118 - 128.]

3. Grimm, Sussan J, How to Write Computer Manuals for Users, Wadsworth, 1982.
[Great title, but a very disappointing book. Low level and mostly common sense.]

4. Heckel, Paul, The Elements of Friendly Software Design, Warner Books, 1984.
[Personal view on how to write friendly software for the PC market. Nice little paperback that is well worth reading.]

5. Pirsiq, Robert M., Zen and the Art of Motorcycle Maintenance, Bantam Books, 1974.
[One of my favorite books! Required reading for all undergraduates! One of the characters in the story is a computer manual writer and, at times, he spouts off on computer manuals and their lack of quality. The paperback is a fictional story that is an inquiry into values.]