Why Manuals Fail
A friend loaned us a copy of Edmond H. Weiss’s How to Write a Usable User Manual (ISI Press, 1985). It’s an older edition, and I can’t really review it because there's a new one on the way, but I couldn’t resist passing on some of its wisdom.
On defining requirements: Deciding what documentation is needed is too important a decision to be made casually or by default. Also, it is too important to be made by one person. Rather, defining what documents are needed calls for at least three perspectives: the technology expert (developer); the application expert (user); the document coordinator (referee).
On the manual for everybody: One of the key tasks in defining specialized documentation needs is to analyze the audiences. The breakdown of readers is critical. It is a serious strategic error to write your documentation as though it were one compendium of material aimed at a universal audience.
On the five phases: The five phases of user documentation are
-
analysis
-
design
-
assembly
-
editing
-
maintenance
All five phases are necessary for effective, usable documentation. Organizations that skip the first two phases will produce documents with all the expensive functional and structural flaws of undesigned computer programs and sloppily engineered machines… People who start at the end—editing and maintaining old publications that never worked well in the first place—are usually wasting their efforts.
On why manuals fail: Much of what is wrong with user documentation is the result of mistakes made before the draft was written, and most serious flaws in user publications are nearly impossible to correct after the (first draft). There are three broad classes of errors that can undermine user documentation—and only one of them can be corrected in the editing stage.
Strategic errors:
-
poor definition of audiences
-
poor definition of tasks
-
lack of overall plan
Structural errors:
-
lack of substantive outline
-
poor tests of outlines
-
omitting users from the review
Tactical errors:
-
careless inconsistencies
-
first draft style
-
subprofessional editing