Designing and Writing Online Documentation News & Views Book Review

Designing and Writing Online Documentation William Horton by Chris Larsen, Principal Consultant, Management Process Integrators, Inc. (Scottsdale, Arizona) Designing and Writing Online Documentation, by William Horton. John Wiley and Sons, Inc. ISBN 0-471-30635-5. Originally published in News & Views March, 1996 issue. Copyright 1996 STC-Philadelphia Metro Chapter. For permission to reprint this article, contact the Managing Editor.

When you need to build a house, you don't want to worry about whether or not you have the right kind of hammer and nails. You want to build the best home you can so somebody can move in and be comfortable. Think of online documentation the same way. So much has been written, taught, presented, demonstrated, and hyped about online document authoring tools that it's all too easy to lose sight of the larger task: building a document that's clear, easy-to-use, helpful, familiar, and even enjoyable to its readers. No authoring tool or multimedia development kit can teach you how to construct the online classic. But William Horton can, and you should not be without his guidance if you're responsible for anything from hypertext to HTML. Boot camp for hypertext authors Horton has just published the second edition of Designing and Writing Online Documentation, which in its first edition was already a well-recognized reference for technical communicators. This book takes you beyond the fog of specific GUIs, help systems, and computing systems to describe what it takes to put knowledge (not just information) onto a screen. It's an Elements of Style for the hyperlink crowd. The first edition (subtitled "Help Files to Hypertext") was published in 1990, when Windows was just a pane and the Macintosh defined graphical computing. Its first sentence reads, "A book is a book, whether on paper or online." In the second edition (subtitled "Hypermedia for Self-Supporting Products"), Horton correctly repudiates that statement by acknowledging that online documentation is "as different from books as television is from radio." A goal of online documentation, he says, is to provide a "question-answering" machine to accompany products. Horton defines what online documentation is (and isn't), and provides criteria to help you decide whether or not a document should go online. He breaks the field down into classes ranging from system messages and read-me files, to help facilities and tutorials, up to huge informational databases. Process and practice After you make the choice to go online, follow Horton's principles for planning an online project: for example, learn about your readers, assemble a multitalented team, and plan to build from reusable components. He provides specific checklists or to-do lists that even experienced online document producers will find useful. Horton then dives into the practical aspects of online documents: access, topics, links, structure, display style (fonts, colors, etc.), and language. For those of us getting sliced on the cutting edge, Horton also delves into the new media--sound, music, voice, video, and animation--and how to integrate it wisely. Two chapters at the end apply his guidelines to two of the most common kinds of online documents: help and computer-based training (CBT). That Horton style His method is to divide subjects into brief, concise components with declarative headings and a razor-edge clarity. The book is packed with detail and examples. Numerous tables and graphics help illustrate practical concepts such as access paths, kinds of linking, topic hierarchies, and so forth. His highly readable, no-frills style lends itself to quick review, and occasionally some chuckles. When people read technical documents, he says, "They skim, they scan, they skip, they flip, they hop, they bounce. They jump all over the place." Perhaps one of the most significant effects of this book is to remind novice and experienced online writers alike of the higher principles behind their work, of their mission to transform information into knowledge. If you're "putting it online," this book should be your bible.

Return to . . .

[News & Views] [STC-PMC Home] [STC Home Page]
Last updated: November 6, 1996 (wq)