DocQment March 2003, Vol. 10, No. 1
Adrienne Escoe’s The Practical Guide to People Friendly Documentation is a textbook for the documenter who strives to organize and create user-friendly documents. The book, a valuable resource for the technical communicator, won the Society for Technical Communication (STC) Touchstone Award for 2001.
The layout of this large volume’s chapters is reminiscent of school days. Each begins with an outline or questions of what will be discussed, and each contains easily followed sections. The tone is instructional with many diagrams and how-tos focusing on how to overhaul your documentation process.
The central theme of the book suggests establishing a litmus test for documentation. “Before any piece is added to a documentation system – for example a new manual, procedure, form, paragraph, phrase, or link – or before a streamlining effort, it is evaluated from a zero base. That means no piece is accepted into the system unless it can be proven to meet clearly defined needs, or its exclusion can be shown to cause possible harm to the organization" (7). This idea is woven throughout the book and informs every further step the author describes.
While reading this book, keep in mind that Escoe does not concentrate on one particular kind of documentation. She does not, for example, spend too much time specifically on Web design or user manuals. Instead, Escoe covers all aspects of documentation: legal documents, human resource papers, procedures, engineering documents, manuals, Web pages, etc. Her main focus is on establishing a documentation process and on how to choose the process that is right for you and your organization.
Figures and diagrams illustrate and emphasize key points. Case studies and real-life examples are also included. These add to the usability because you can create a procedure based on what someone else’s document actually looked like. The book contains handy checklists for a given process or situation a documenter might face. Examples include checklists on “E-mail Etiquette,” “Considerations for Standardization,” and “Ingredients for Team Success.” These checklists have a series of questions and requirements to steer you in the right direction.
Chapter four, “Usability,” is a good example of the book’s methodology. It focuses on making documentation not just effective, but usable. Escoe writes, “Ironically, some of the poorest-quality documentation we have seen is intended to fulfill the requirement of quality programs …” (63). The chapter’s five sections help writers increase usability in different areas: Usability Testing, Readability, Web Design, Internationalization, and Presentation Slides.
The one pitfall in this book is the use of catch terms, such as Nimble Documentation®, and theories without immediate adequate explanation. However, the book does have a good index. An elusive term usually appears in the index, and from there the full meaning can be quickly located.
Summarily, this book would be ideal for a company that is overhauling its documentation process, or for a company that has suddenly grown large and has documentation uniformity issues to address. It would also be useful for the beginning documenter, or a documenter who is thinking about changing how his/her department goes about the documentation process.
To view a section of this book, visit the American Society for Quality (ASQ) Web site (http://qualitypress.asq.org/perl/catalog.cgi?item=H1100).
Reprinted from the July/August 2002 issue of The Nor’easter, newsletter of the STC Northern New England Chapter.