212 IEEE TRANSACTIONS ON PROFESSIONAL COMMUNICATION, VOL. 44, NO.

3, SEPTEMBER 2001

Gretchen Hargis
Developing Quality Technical Information—
A Handbook for Writers and Editors

Book Review Index Terms—Online help, program documentation, quality.

—Reviewed by
RAYMOND E. FLOYD,
H argis’ Developing Quality
Technical Information would
references are again grouped as
sources that provide information
SENIOR MEMBER, IEEE that is Easy to Use, Easy to
be a valuable addition to
Understand, and Easy to Find.
any professional’s bookshelf,
especially if the reader is
involved in developing technical For each of the three main sections,
Manuscript received January 12, 2001; the author identifies a number
revised January 20, 2001. documentation on application
The reviewer is with programs, operating systems, of keywords, corresponding to
Innovative Insights, Inc., online HELP systems, or webpages. features that contribute to quality,
PMB 416, It may be used as a student text, and then develops the text around
Cody, WY 82414 USA these words to provide insight into
(email: [email protected]). but it does not appear to have a
broad enough focus to prepare a the “how to” process of developing
IEEE PII S 0361-1434(01)07493-8.
student for using general technical quality technical information. The
Book Publisher: writing skills. While the focus is on words are
Upper Saddle River, NJ: • Easy to Use: task orientation,
Prentice-Hall, 1997,
quality technical information, the
298 pp. plus index. primary vehicle for illustration is accuracy, and completeness;
software. • Easy to Understand: clarity,
concreteness, and style;
As a preliminary note, it is unclear • Easy to Find: organization,
who is the author of this text. The retrievability, and visual
cover clearly identifies Gretchen effectiveness.
Hargis, but the facing page and
the “Welcome!” Section identify The intent of the text is to help
five additional names: Ann Kilty technical writers develop skills
Hernandez, Polly Hughes, Jim to write quality technical books,
Ramaker, Shannon Rouiller, and guides, brochures, and other
Elizabeth Wilde. Since they have material for products. Central to
been so identified, any reference to that effort is the focus on “the user”
author in this review is intended and the effect the user should have
to include all. on the technical writer’s efforts.
This focus is established early:
The book is organized into five “You need to build on the user’s
parts, with the division supporting knowledge and speak the user’s
the central theme of quality in language. You can perform a task
documentation. The first three analysis to better understand
parts set the stage, focusing on your users and their tasks. You
the most important qualities of can monitor users as they work,
technical information. Those three interview them about their tasks,
qualities are that it be or survey a set of users” (p. 5), and
“The more you understand about
• Easy to Use
the users and their tasks, the
• Easy to Understand
easier it is for you to write relevant,
• Easy to Find
task-oriented information” (p. 6)
These qualities are repeated later The importance of understanding
in the Bibliography, where the user needs and of writing to user

0361–1434/01$10.00 © 2001 IEEE

skills and knowledge levels is icons are well thought out and should be at least one reference in
repeated often. Although the word provide the reader with instant the Index (there is not). Conversely,
“user” is only given eleven entries identification of the material’s with eight references to icon in
in the index, it could have been intent. the Index, it would, again, seem
given over a hundred if the author appropriate that it be defined
had wished to do so. The emphasis The two chapters in Part 4, in the Glossary for those who
on the importance of the user is “Putting It All Together,” provide may not be sure of its intended
brought to the attention of the insight into how the parts go definition. Perhaps this is part
reader again and again. together, overlapping and fitting of the consistency, clarity, and
into the whole package for the completeness to be strived for. In
The author uses the three themes user. It should come as no surprise addition, there are some typos
and the quality characteristic that the icon for this section is throughout the text that may
words to introduce approaches a jigsaw puzzle comprised of all strain the author’s credibility,
to writing technical information. of the previously used chapter especially given the topic of the
Part 1, “Easy To Use,” consists of icons. This part also addresses book.
three chapters, and it should be the various roles and resources
no surprise that they are entitled that an author may use to develop The author has provided an
“Task Orientation,” “Accuracy,” a quality product: technical inordinate number of examples of
and “Completeness.” The author reviewers, human factor engineers, poor technical writing, followed
has established the premise and graphic designers, and editors. by revised illustrations, and
the direction, and pursues the sometimes with more than one
material presentation toward that The author completes the text revised example to illustrate the
goal. Part 2, “Easy to Understand,” by including a Part 5, which value of review. Unfortunately,
consists of three chapters entitled contains four appendixes dealing this text was developed in
“Clarity,” “Concreteness,” and with quality checklists, task a programming development
“Style,” while Part 3, “Easy to assignments, a quality summary, laboratory (IBM’s Santa Teresa
Find,” consists of three chapters, and words that can cloud clarity. In Laboratory) and was written to
“Organization,” “Retrievability,” addition, the author provides the help technical writers in that
and “Visual Effectiveness.” Having previously mentioned Bibliography environment prepare technical
established an excellent structure, in the Easy to … approach, and information concerning programs,
the author then presents the a Glossary. It is interesting to programmer’s reference material,
information using that structure note that all of the books in the and user’s reference material. As
and the guidelines within it, a Bibliography are relatively new, a result, all of the examples are
strategy too often forgotten by most being published in the of programming-related subjects,
other authors. mid-1990s. replete with programming jargon,
definitions, code examples,
One eye-catching feature of this The author has written an excellent and slang. To benefit from the
text it the author’s use of icons for text for use by some technical examples, a technical writer
each chapter as visual reminders writers. There are, however, a unfamiliar with programming
of each chapter’s theme. The icon, couple of items that, if corrected, jargon must look at the example
for example, for task orientation would help the text be of greater from a distance to understand the
is a set of steps (the task), and a use to an even larger audience. The intent of the example, and not be
compass (orientation). This icon is first item concerns entries in the confused by the content of it. The
placed at the top of each page in Glossary and Index. It would seem need to concentrate in this manner
the chapter, a constant reminder that if a word, such as scenario, is may detract from an otherwise
of the theme being presented. The defined in the Glossary, then there excellent book.