Many books about 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 that you will find the information in this book easy to use, easy to understand, and easy to find!
If you are a writer, editor, or reviewer of technical information—yes! If you write, edit, or review software information, this book might be of even more interest to you because most of the examples in it come from the domain of software. However, the quality characteristics and guidelines apply to all technical information.
Reviewers can be any of the many people who are involved in developing technical information:
Writers
Editors
Visual 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.
You can use the book in any of several ways, such as:
Read the book from start to finish.
Read about the particular quality characteristic or guideline that interests you.
Read Chapter 11, “Applying more than one quality characteristic 1,” on page 331 to see how the quality characteristics interact, and then read the particular chapters that fit what you're working on.
Use the checklists at the end of each chapter and Appendix A, “Quality checklist,” on page 387 to evaluate a piece of technical information by using the quality characteristics.
Use Appendix B, “Who checks which quality characteristics?,” on page 391 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.
Nine of the twelve chapters in this book deal with the quality characteristics, one per chapter. Each of these chapters has a series of guidelines about how to enhance the particular quality characteristic.
Within each guideline, this book uses examples, usually in pairs of an original passage such as you might see in technical information and a revision that demonstrates the application of the guideline. Some passages go through more than one revision. The descriptions of the guideline and of the examples aim to help you understand and implement the guideline.
In addition, each of the nine chapters ends with a checklist. This checklist indicates the items to look for when you evaluate a piece of technical information by using the guidelines for the particular quality characteristic.
The basic organization of the book and the quality characteristics remain the same. However, within each quality characteristic, we have added, reworded, deleted, or moved some guidelines and subguidelines, and we have updated many examples. For example, the following guidelines are among those that we added:
“Organize information into discrete topics by type.” (Organization chapter)
“Facilitate navigation and search.” (Retrievability chapter)
“Ensure that all users can access the information.” (Visual effectiveness chapter)
These changes resulted from several developments in technical communication:
Greater emphasis on topic-based information and single source
Internationalization of information and increased delivery of technical information on the Web
The need to make technical information accessible to people with disabilities such as blindness and deafness
As with earlier developments in this field during the 20 years that these quality characteristics have been in use, the characteristics have been able to absorb the changes. This framework continues to apply to the information that we are called on to provide today.
We hope that you find this book useful in improving the quality of the information that you develop.
Gretchen Hargis
Michelle Carey
Ann Kilty Hernandez
Polly Hughes
Deirdre Longo
Shannon Rouiller
Elizabeth Wilde
In fond memory of our tireless lead author, Gretchen Hargis
After this second edition of Developing Quality Technical Information was published, its lead author and project manager, Gretchen Hargis, passed away. Throughout the writing process for both editions of this book, Gretchen was vigorous in pushing the writing team to do what was necessary to make the book as good as it could possibly be. We planned, we drafted, we edited, we haggled, we revised, we re-edited, we proofread. Throughout the process, the concept of “good enough” never entered Gretchen’s mind. Sometimes, Gretchen’s coauthors wished “good enough” had been just that, but in retrospect we are so glad that Gretchen persevered. Let there be no doubt: Without Gretchen, neither the first nor second edition of the book would ever have been completed. Gretchen is sorely missed by all of her coauthors and colleagues.