Computing Reviews
Today's Issue Hot Topics Search Browse Recommended My Account Log In
Review Help
Search
Writing user documentation
Low R., Ford H., Pallot J., Hall J., Prentice Hall International (UK) Ltd., Hertfordshire, UK, 1994. Type: Book (9780133368352)
Date Reviewed: Jun 1 1995

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
Bookmark and Share
 
Training, Help, And Documentation (H.5.2 ... )
 
 
User/ Machine Systems (H.1.2 )
 
Would you recommend this review?
yes
no
Other reviews under "Training, Help, And Documentation": Date
Designing and writing online documentation: help files to hypertext
Horton W., John Wiley & Sons, Inc., New York, NY, 1990. Type: Book (9789780471507727)
Feb 1 1992
Designing, writing and producing computer documentation
Denton L. (ed), Kelly J., McGraw-Hill, Inc., New York, NY, 1993. Type: Book (9780070164178)
Oct 1 1994
An integrated solution
Hutchinson M., Rockley A.  Systems documentation (, Waterloo, Ont., Canada, Oct 5-8, 1993)1471993. Type: Proceedings
Sep 1 1994
more...

E-Mail This Printer-Friendly
Send Your Comments
Contact Us
Reproduction in whole or in part without permission is prohibited.   Copyright 1999-2024 ThinkLoud®
Terms of Use
| Privacy Policy