Writing Better Computer User Documentation: From Paper to Hypertext, Version 2.0

Rating:
Summary: If you want flashy layout, read Wired...
Review: ...but if you want a good introduction to solid principles of computer documentation, this is a good place to start. Wiley's collection of books for technical writers certainly contains some more detailed volumes, but Brockmann's book is a good starting point for less-experienced documentation authors.

Rating:
Summary: The Best Book on Documentation
Review: John Brockmann has raised the occupation of Technical Writing to the academic level and for that we owe him a huge debt of gratitude. I came into the industry when it was housewives who were bored, crackpots and all kinds of strange characters. The idea was that engineers couldn't communicate with users, so plain ordinary folks were hired in order to do it. The result was often folksy, but silly. Then writers who had experience in writing but who wanted to make some decent money at it were coming into the profession because the money is in the computer industry. That improved the results much, but there was still lacking an academic and theoretical foundation. Some junior colleges offered certificates in Technical Writing and a few Universities offered bachelor's degrees, but this was more the exception than the rule. The one who has had the most exposure and most acceptance in offering a theoretical and academic underpinning to what we do as Technical Writers is R. John Brockmann. I have to admit I liked the version 1 of the book better, because it was less funky. This version still retains the meat and potatoes of the first version: principles of how to write a documentation blueprint, how to organize information, how to index it, etc. It's worth reading and reading again.

Rating:
Summary: Excellent content, atrocious presentation, getting dated
Review: The excellent content of this book is hidden behind a particularly atrocious design, and it is getting dated.

Brockmann's advice is solid, often based on empirical research (very well referenced), and systematic; yet the poor design -- bad fonts, bad paper, bad layout, bad diagrams -- undermine the quality of the content. Even in 1990, a specialist in documentation should have known better.

Some areas are now seriously out of date: Online help is completely obsolete; Web-based techniques are non-existent; tools are old; screen-shots are quaint. Still, most of it is as valid as ever.

The high-quality text cries out for a thorough updating and redesign leading to a new edition, as most of its content is not only still true, but very valuable. Until then, despite its very real qualities, I can only recommend it with strong reservations.