P&P Policies and Procedures Consulting
P&P Policies and Procedures Consulting

Subscribe to
The Policies & Procedures Authority Newsletter

Our Resources

Writing Revisable Manuals – Print and Online

Book review by Raymond E. Urgo

Duncan Kent. 1998. Scarborough, Ontario: Carswell Thomson Professional Publishing.
[ISBN0-459-56346-7. 260 pages, including index and software formatting template.
$95 Cdn. $60 US (loose-leaf binder).]

Given the many books on documentation development, Writing revisable manuals – print and online stands out primarily because it reflects state-of-the approaches for developing manuals while exemplifying what Duncan Kent writes for others to practice. This publication also stands out for being readily usable by a diverse audience, effectively written and edited, and comprehensive in its coverage of topics for print and online manuals.

A diverse audience can benefit from Writing revisable manuals. The novice writer of a manual, whether a subject matter expert or a technical communicator, should find this publication easy to use. Policies and procedures writers, whose information is usually in constant revision, will find this book beneficial if they want to use modular and structured documentation approaches for their manuals. Publication managers and seasoned technical communicators should find this book useful as a supplementary reference source for the up-to-date approaches, terminology, and explanations about manuals for print and online. Individuals and organizations unable to invest time or money in attending documentation development seminars will find Writing revisable manuals an excellent self-learning tool because of its writing style, comprehensive yet detailed coverage of topics, and resource tools included. Technical communication instructors can use this publication as a guide or chosen textbook for their courses on developing manuals.

The book is well written and edited for easy access to and use of information. In addition to the detailed table of contents which spans six pages, users would probably benefit from a summary table of contents to more quickly scan the many parts of the manual: ten chapters, five appendices, a glossary, and an index. The publication has an even flow of information throughout, neither over nor under concentrating on topics, issues, and explanations. Kent’s publication is friendly, using such words as “you”, “we” and “us” throughout. He does more than give tips, guidance, and steps. He thoroughly explains the rationale for what he advises.

Writing revisable manuals offers more than just information on writing manuals—it is a model manual accompanied by tools for users to create their own manuals. As a model manual, it exemplifies what the author says about effective practices for writing revisable manuals. The publication reflects the principles, look, and feel of a manual that can be revised. For example, the publication is even published in a loose-leaf binder. The publication’s tools include a formatting template, for use with popular word processing software, and instructions for using the template. Another tool is a style guide which Kent encourages users to copy and adapt for their respective needs.

Kent’s publication is also notable for its coverage of the documentation development process and the principles of effective documentation. He goes beyond the boundaries of a single manual by addressing the importance of the documentation hierarchy—a manual in relation to other manuals. He clearly defines ten kinds of revisable manuals (p. 1-5). In Chapter 2, Kent provides guidance on audience analysis, including dealing with multiple audiences and ways to assign priority in making planning decisions about the manual. He offers a sample outline and progress report for managing documentation projects. He gives tips on setting up a filing system for both print and electronic purposes. Finally, he advises on dealing with reviewers who are added at the last moment and why reviewers should not be given word processing files for their reviews.

Concerning effective documentation for revisable manuals, Kent recommends limiting the number of levels in the text hierarchy to three or four to avoid confusing the reader. He presents ways of choosing and constructing headings and of writing, structuring, and organizing modules of information for easier use and revision. Chapter 6 includes a decision table to assist the reader in choosing which of more than 16 methods of presenting information is appropriate. Some of the methods include sidebar texts, checklists, tables, step-by-step procedures, playscript, graphics, and flow diagrams. Although these methods are not discussed to meet the needs of advanced learners, Kent provides useful examples and plentiful tips for each method. He does not address the functionality of information types, such as when and how to communicate a process, procedure, policy, and concept. Other chapters cover basic grammar and helpful techniques on applying word processing technology for creating indexes and cross-references.

Kent provides comprehensive advice and tips that go beyond the mere advantages and disadvantages of print versus online manuals. He discusses the importance, considerations, and techniques of using the strategy called single sourcing (p. 2-34). In Chapter 5, he provides details on a variety of aspects often not considered: page vs. screen design; title page vs. home page; index vs. search capability; cover or binder vs. wallpaper, banner, and navigation buttons; and even reader feed back (printed form vs. electronic form or email button).

Because Writing revisable manuals offers and exemplifies up-to-date, comprehensive coverage on writing manuals for print and online, readers stand to gain or solidify their expertise in developing highly usable manuals.

Raymond E. Urgo, principal of Urgo & Associates, specializes in policies and procedures communication. His experience in this discipline includes consultant, author, speaker, and judge. Urgo teaches policies and procedures at UCLA Extension. He founded STC’s Policies & Procedures Special Interest Group (SIG). He is STC’s Assistant to President for SIGs.

Copyright 1999, Raymond E. Urgo
Urgo & Associates, Los Angeles
www.urgoconsulting.com

Published in the Technical Communication journal (Nov 1999),
Society for Technical Communication

Request permission to reprint an article