Technical Book Review: "How to Write Usable User Documentation"

How To Write Usable User Documentation (Second Edition) by Edmond H. Weiss is a thoughtful book on technical documentation written by a professional who obviously knows his material very well. Yet, overall, from its content to its format, this is also a book that shows its age. Published back in 1991, many of the topics in it have either become obsolete (like 25% of its pages devoted to online publications and user interface) or redundant due to the fact that they have been adopted widely today (like structured and modular approach to documentation). For beginner technical writers, however, it still contains brilliant servings of practical advice and inspiration.

There is one theme in this large-format and easy-to-read book that keeps coming up time after time, in more chapters than one: redundant versus non-redundant writing. That is, whether one should repeat modular information in different chapters of a document at the risk of redundancy, or should one write everything once (in a strict “structured” fashion) and then send the reader to the relevant section/chapter by following a “GOTO statement” of “See …” reference.

The author sides with repeating things and risking redundancy rather than losing the readers in confusing back-and-forth movements through a document. I agree with Weiss on this point, although if you are working in an organization with other technical writers there’s always a discussion of and even resistance to the idea, on a case-by-case basis. But since user comfort and comprehension is always more important for me than the aesthetic elegance of a document, I’d always vote for a longer document (since it has redundant passages in it) over a shorter one with a lot of GOTO statements.

There is actually a very solid reason to choose redundancy over conciseness; a reason that becomes more important with every passing day: readers do not read anything from cover to cover anymore. They just want to go directly to the “help topic” that interests them, read it, and move on. If a certain modular procedure that is repeated in multiple tasks is offered only in one corner of a document and the reader is invited to go visit that section repeatedly from different parts of the document, that kind of traffic will create a difficult reader experience for sure. Yes, in this day and age of HTML links one can (and should) insert links that would take the readers back to where they were initially but the maintenance and accuracy of those links also become a formidable document management issue as the number of “pages”, “sections” and links increase. To use an Americanism: “there’s no free lunch” in life.

It’d be wonderful if the author could prepare a new edition and bring this comprehensive volume up to date. It’s amazing how the technical communication landscape has changed during the last twenty years. The shortcoming of this book is totally due to such unprecedented changes we have lived through since the invention of the Internet. That’s why reading it is not only an excellent introduction to technical documentation but also a lesson in historic change since the book feels like a “time capsule” in many of its chapters, displaying a static cross-section of the way things were twenty years ago.