Computing Reviews
Today's Issue Hot Topics Search Browse Recommended My Account Log In
Review Help
Search
Writing better computer user documentation: from paper to hypertext (version 2.0)
Brockmann R., John Wiley & Sons, Inc., New York, NY, 1990. Type: Book (9780471622598)
Date Reviewed: Oct 1 1991

End user documentation seems to be one of the most difficult forms of product support to do well. Even experienced technical writers have an easier time working up documents directed at engineers or maintenance technicians than trying to write materials for the mystical end user. Why this should be the case often seems a mystery. Fortunately, we have Brockmann to help penetrate the fog.

The first part of Brockmann’s book examines the problem, explaining why it exists and examining potential solutions such as CASE tools and online support. These potential solutions are critically appraised, as they should be. This first part is not crucial to the value of the book, however.

Part 2, “The Standard Documentation Process,” is the heart of this book, comprising over 50 percent of the pages. It consists of a detailed examination of a nine-step documentation process. The steps are specification development, prototyping, drafting, editing, reviewing, field-testing, publishing, post-project review, and document maintenance.  Brockmann  puts these steps together in a sensible and practical way. If you have ever done any technical documentation, you will want to get right to work putting his ideas into practice. The first step, developing the document specifications, gets the bulk of Brockmann’s attention (the 110 pages devoted to it are nearly one third of the text). Many documenters would agree with this approach, arguing that documentation is analogous to systems development, with more time spent in specification paying off later in the project.

While I agree with the last statement, the book does have some shortcomings. The chapter on field-testing is a skimpy three pages, and it provides almost no guidance on how to conduct the process, what the common obstacles will be, or how they may be overcome. I also object to the use of “hypertext” in the book title. While alternatives to traditional documentation are surveyed well, this book is essentially on conventional documentation techniques. The extremely complete index cites only seven different pages under the term hypertext, which gives an accurate indication of the book’s coverage. While a detailed discussion of typefaces attempts to justify the author’s choice of an unusual one, it looks too much like it came from an old typewriter for my taste. Not all of these shortcomings may be significant to the reader.

All in all, I find Brockmann to be one of the finest technical writers in the profession. While we would never recognize one another, we have both spoken at the same meeting of the ACM Special Interest Group on Documentation (SIGDOC), where he continues to bring forth useful and practical ideas. In his book, he lives up to his reputation. The index is complete, the writing style is relaxed, and the book is filled with examples and tips. As a practical guide to the process of creating technical documentation, this book is first rate.

Reviewer:  David Bellin Review #: CR123491
Bookmark and Share
  Featured Reviewer  
 
Documentation (D.2.7 ... )
 
 
Document Preparation (I.7.2 )
 
 
Management (D.2.9 )
 
Would you recommend this review?
yes
no
Other reviews under "Documentation": Date
Illustrating computer documentation
Horton W., John Wiley & Sons, Inc., New York, NY, 1991. Type: Book (9780471538455)
Jun 1 1992
The art of technical documentation
Haramundanis K., Digital Press, Newton, MA, 1992. Type: Book (9781555580803)
Jun 1 1992
Integrated hypertext and program understanding tools
Brown P. IBM Systems Journal 30(3): 363-392, 1991. Type: Article
Nov 1 1992
more...

E-Mail This Printer-Friendly
Send Your Comments
Contact Us
Reproduction in whole or in part without permission is prohibited.   Copyright 1999-2024 ThinkLoud®
Terms of Use
| Privacy Policy