Developing Quality Technical Information: A Handbook for Writers and Editors

Hernandez, Ann Kilty; Hughes, Polly; Ramaker, Jim; Rouiller, Shannon; Wilde, Elizabeth

ISBN 10: 0137903200 ISBN 13: 9780137903207

Publisher: Prentice Hall, 1998

Synopsis

This is a method tested reference guide (developed over 10 yrs. at IBM's technical Info Labs) for technical writers and editors in communication and engineering companies. It features extensive examples, illustrations and before and after excerpts from real technical information to help the reader/user become a very competent writer or editor.

About this title

From the Inside Flap

Welcome!

Many books on technical writing tell you how to develop different parts of technical information, such as headings, lists, tables, and indexes. Instead, we organized this book to tell you how to apply quality characteristics that, in our experience, make technical information easy to use, easy to understand, and easy to find. We hope you will find our approach useful and comprehensive—and we hope you will find the information in this book easy to use, easy to understand, and easy to find!
Is this book for you?

If you are a writer or reviewer of technical information—yes! If you write or review software information, this book may be of even more interest to you because the examples in it come from the domain of software. However, the quality characteristics and guidelines are universal to all information.
Reviewers can be any of the many people who are involved in developing technical information:

Writers Editors Graphic designers Human factors engineers Product developers and testers Customer service personnel Customers (perhaps as early users) Managers

In general, this book assumes that you know the basics of good grammar, punctuation, and spelling as they apply to writing. It does not assume that you are familiar with what makes technical information good or bad.
How to use this book

You can use the book in any of several ways:

Read the book from start to finish. Read about the particular quality characteristic or guideline that interests you. Use the checklists at the end of each chapter and "Quality Checklist" on page 269 to evaluate a piece of technical information against the quality characteristics. Use "Who Checks Which Quality Characteristics?" on page 273 to see what areas you as a reviewer need to check, and read those sections.

Whatever your role in developing technical information, we hope that you'll use this information to build these quality characteristics into the information that you work on.

Changes in this edition

The first and second editions were published in 1984 and 1986 for use mainly by developers of information for IBM software products. This edition is published for more general use and takes into account these changes in technical information:

Online information (such as help, tutorials, and documents) is often more important than printed information in the documentation of software. Online information has become more integrated with the product user interface, through forms such as cue cards and wizards.

As a result of comments from customers and editors, we have:

Added two quality characteristics: concreteness and style

Feedback from users showed that, to them, examples and scenarios are not only very important, but also generally lacking or poorly handled in computer information. The first edition treated examples as part of clarity, but clarity has many other aspects as well. In this edition we have added concreteness as the quality characteristic that focuses especially on examples and scenarios.
In the first edition, style considerations were spread across accuracy, clarity, and visual communication. We decided that style needs its own focus.
Renamed two quality characteristics

The earlier name "entry points" has become "retrievability," and "visual communication" has become "visual effectiveness."

In addition, we have reorganized the book into parts and added several sections:

Introduction to help define terms and set the context for the information Chapters 11 and 12, which treat more than one quality characteristic Annotated bibliography Glossary of terms used in this book Index

The technical editors at IBM's Santa Teresa Laboratory use these quality characteristics to assess the quality of the information they edit. In this edition, we have revised some guidelines and added more examples to ensure coverage of the kinds of common errors found every day.
Gretchen Hargis Ann Kilty Hernandez Polly Hughes Jim Ramaker Shannon Rouiller Elizabeth Wilde

From the Back Cover

The #1 guide to excellence in documentation!

Create documentation that even the most demanding users will appreciate!

All you need to deliver top-quality technical information -- in print, online, and on the Web! Extensive, practical before-and-after examples Sample windows, illustrations, excerpts, tables, checklists, and more Smarter ways to use visuals Based on the experience of professionals at an IBM software laboratory for over 10 years For every writer, editor, designer, and reviewer of technical information

Straight from IBM's own software documentation experts, this is the first practical guide to developing excellent technical information.

From start to finish, you'll learn how to create documentation that's easy for users to find, understand, and use.

Discover how to make sure your documentation focuses on the tasks and topics users care about. Learn style points and organization techniques that help users access information quickly -- and use it effectively. See how to use graphics and other visual elements to deliver useful information in inviting ways. Walk through the review process, and learn ways to add the most value using minimal words.

Whether you're a writer, editor, designer, or reviewer, if you want to create great documentation, this book shows you how!

“Developing Quality Technical Information is unequaled in the field today as a comprehensive textbook on how to do technical communications right. Every technical communicator around the world can surely apply this model to their information; those that do so systematically will surely see an improvement in the quality of their deliverables." Lori Fisher, Manager, Data Management User Technology, IBM; Instructor, University of California Extension Santa Cruz

"The writers have done an excellent job of keeping the editorial advice simple and clear enough for technical writers who didn't major in English or journalism. The book should make a very good technical writing and editing text in universities, but I think it will be even more valuable for experienced writers, editors, and managers concerned with raising the quality of their publishing programs." Carolyn Mulford, Freelance Writer and Editor Instructor, Georgetown University Continuing Education

Edition details

• Publisher: Prentice Hall
• Publication date: 1998
• ISBN 10: 0137903200
• ISBN 13: 9780137903207
• Binding: Textbook Binding
• Language: English
• Edition number: 1
• Number of pages: 310
• Editor: Hargis Gretchen