Computing Reviews

Writing user documentation
Low R., Ford H., Pallot J., Hall J., Prentice Hall International (UK) Ltd.,Hertfordshire, UK,1994.Type:Book
Date Reviewed: 06/01/95

A wide variety of topics are covered in widely differing depths in this short volume. Although the authors endeavor to generalize, the overall setting is that of a contracted documentation project, where writers and editors are “us,” and reviewers and owners (clients) are “them.” In that view, a synopsis is a proposal in the form of a compendium of the product (with some elements of a prototype). The book is part of the British Computer Society’s practitioner series, and I agree with the series editor’s statement in the preface that “anybody who has to write any form of documentation should find useful ideas in here.”

The book offers a broad range of anecdotal material and many hints, including (for the British) being wary of American spell-checking routines, “soothing the battered ego,” negotiating prices with print shops, and proper use of trademarks and the asterisk. Strategy for a kickoff meeting is discussed. An entire chapter is devoted to maintaining the owner’s (client’s) confidence; another covers having documentation translated. There is even a section on “Dealing with Writer’s Block.” Useful material on design appears in several contexts, although it is best to work with a professional designer. Properly, much attention is paid to the matter of audience, and indeed multiple audiences (and therefore perhaps multiple books). The audience is considered not only in relation to document content and layout, but also in terms of the physical characteristics of the volume. Three basic printing methods and five binding methods are covered, and attention is paid to the user’s environment. (Will a big binder cover up other work on the desk? Can a supplemental laminated card be provided for the nurses’ station?)

Online documentation, straightforward or hypertext, is not covered in appreciable depth. “Investigation,” the portion of a documentation project in which the writers obtain the information contained in the documentation, is depicted primarily by example and horror story. The chapter “The Qualities of a Good ‘Technical’ Writer” includes a statement that may not comfort those of us who are in one way or another responsible for the documentation of systems: “To a large extent, writers are born and not made.”

Reviewer:  T. C. Lowe Review #: CR118168

Reproduction in whole or in part without permission is prohibited.   Copyright 2024 ComputingReviews.com™
Terms of Use
| Privacy Policy