Developing Quality Technical Information: A Handbook for Writers and Editors [Hardcover]

The book presents a much needed approach to quality technical communication and a working plan for achieving quality. The examples are excellent and are easy to use and adapt. The editorial advice is simple and clear enough for tech writers who did not major in English or journalism. It is most worthy of a text in university programs, but it is more valuable to experienced writers, editors and managers concerned with raising the quality of their publications. The main difference between this and other books is that in each of the first nine chapters, one quality characteristic is presented that you can apply to your writing project to make technical information easy to use, easy to understand and easy to find. There are checklists at the end of each chapter for review and a Quality checklist in the appendix covering all of the characteristics. The book shows original text and revision text so that you can actually browse the book and see the differences applied. This is another excellent feature that should catch a purchaser's eye.

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!

Is this book for you?

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.

How to use this book

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.

Conventions used in this book

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.

Changes in this edition

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