Writing Software Documentation: A Task-Oriented Approach and Read Me First! A Style Guide for the Computer Industry News & Views Book Review

Writing Software Documentation: A Task-Oriented Approach, by Thomas T. Barker Allyn and Bacon 1998. ISBN 0-205-19576-8 $38.00 484 pp. by Cheryl Cherry Freelance Writer Originally published in News & Views March 1998 issue. Copyright 1998 STC-Philadelphia Metro Chapter. For permission to reprint this article, contact the Managing Editor.

A task-oriented guide to task-oriented writing Barker, a professor at Texas Tech University, practices what he preaches. After the introductory section defining task orientation, he guides writers through the process of creating a manual. He includes: Analyzing Your Users Constructing a Task List Planning and Writing Your Documents Getting Useful Reviews Conducting Usability Tests Editing and Fine-Tuning Designing for Task Orientation Laying Out Pages and Screens Getting the Language Right Using Graphics Effectively Writing to Teach - Tutorials Writing to Guide - Procedures Writing to Support - Reference Designing Indexes Users, not software, in control Barker encourages writers to help software users feel in control of a program, instead of controlled by it. He stresses the importance of showing readers how to make key decisions about using the software. He also encourages writers to use design elements such as hypertext links in online systems and cross-references in printed manuals to aid readers in taking control of their use of documentation. Reading to do vs. reading to understand Barker has facilitated selective reading by his arrangement of information. Each chapter contains examples, most from real documentation. These examples are followed by guidelines for the reader faced with the immediate problem of producing a software manual. The guidelines are followed by a discussion of the ideas behind the guidelines, for readers with time to focus on the "why's". Each chapter also includes a checklist, summary, and glossary. These aid in understanding the chapter and make it easy to go back to look at key points in earlier sections. Focus on the user, not the software Instead of describing the software's human interface, he encourages writers to help users perform real-world tasks. Because of this emphasis, his pie chart for the process of creating software documentation devotes almost half the time to pre-writing tasks. He also uses a significant percentage of the remaining time for conducting reviews and tests. Ideal vs. real Barker acknowledges that writers will not always have time to follow all his guidelines. He includes some suggestions for cutting corners and speeding up the process of manual creation. (Perhaps he should have given newbies a stronger dose of reality about the challenges faced when trying to devote sufficient time to user analysis and planning.) Focus on how people think and learn Barker stresses the importance of taking into account what the reader brings to the task of constructing meaning from text: prior knowledge of the subject covered (or lack of knowledge) and a mental model ("cognitive schema") of the information. Good teachers have known for years that students need to link new knowledge to something that is already in their heads. Without this link, the new knowledge will not stick with them. Warning: The least successful element of the book is its page design. Unfortunately, contrary to Barker's advice, some pages are cluttered. It is difficult to determine the hierarchy of the subheadings without referring back to the Table of Contents. Many of the illustrations consisting of text are not clearly separated from the text of the book, hindering rapid reading. Do not let this weakness discourage you from extracting Barker's wisdom from the pages; he has a lot of good advice for beginners.

Read Me First! A Style Guide for the Computer Industry, by Sun Technical Publications SunSoft Press 1996. ISBN 0-13-455347-0 $29.95 256 pp.

Not new, but noteworthy Although this book does include concise coverage of the mechanics of writing, its greatest value may be in the sections providing less widely available information. For example, sections on legal issues and writing for an international audience set this apart from typical style guides. Especially good were the brief but thorough chapter in indexing, and the chapter for the graphically-impaired that provides guidelines for designing illustrations, and for formatting and placing call-outs. The book includes a CD containing FrameViewer (for Mac, Windows, and Solaris 2.x), HTML files for the book, and sample Framemaker templates.

Return to . . .

[News & Views] [STC-PMC Home] [STC Home Page]
Posted May 8, 1998 (dls)