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.