Developing quality technical information: a handbook for writers and editors

464 Pages·2004·4.762 MB·English

by  Hargis, Gretchen;Hughes, Polly;Carey, Michelle

Developing Quality
Developing Quality
Technical Information
Technical Information
A Handbook for Writers and Editors
A Handbook for Writers and Editors
Gretchen Hargis • Michelle Carey • Ann Kilty
Gretchen Hargis • Michelle Carey • Ann Kilty
Hernandez • Polly Hughes • Deirdre Longo •
Hernandez • Polly Hughes • Deirdre Longo •
Shannon Rouiller • Elizabeth Wilde
Shannon Rouiller • Elizabeth Wilde
PRENTICE HALL
PRENTICE HALL
Professional Technical Reference
Professional Technical Reference
Upper Saddle River, New Jersey 07458
Upper Saddle River, New Jersey 07458
www.phptr.com
www.phptr.com
The authors and publisher have taken care in the preparation of this book, but make no expressed or
implied warranty of any kind and assume no responsibility for errors or omissions. No liability is
assumed for incidental or consequential damages in connection with or arising out of the use of the
information or programs contained herein.
© Copyright 2004 by International Business Machines Corporation. All rights reserved.
Note to U.S. Government Users: Documentation related to restricted right. Use, duplication, or
disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.
IBM Press Program Managers: Tara Woodman, Ellice Uffer
IBM Press Consulting Editor: Susan Visser
Cover design: Talar Boorujy
Published by Pearson plc
Publishing as IBM Press
Library of Congress Cataloging-in-Publication Data is on file with the Library of Congress
IBM Press offers excellent discounts on this book when ordered in quantity for bulk purchases or
special sales, which may include electronic versions and/or custom covers and content particular to
your business, training goals, marketing focus, and branding interests. For more information, please
contact:
U.S. Corporate and Government Sales
1-800-382-3419
[email protected].
For sales outside the U.S., please contact:
International Sales
[email protected].
The following terms are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both: DB2, Lotus, Tivoli, WebSphere, Rational,
IBM, the IBM logo, and IBM Press. Java and all Java-based trademarks are trademarks of Sun
Microsystems, Inc., in the United States, other countries, or both. Microsoft, Windows, Windows
NT, and the Windows logo are trademarks of the Microsoft Corporation in the United States, other
countries, or both. Linux is a registered trademark of Linus Torvalds. Intel, Intel Inside (logo),
MMX, and Pentium are trademarks of Intel Corporation in the United States, other countries, or
both. OSF/1 and UNIX are registered trademarks and The Open Group is a trademark of the The
Open Group in the United States and other countries. Other company, product, or service names
mentioned herein may be trademarks or service marks their respective owners.
All rights reserved. This publication is protected by copyright, and permission must be obtained
from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmis-
sion in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For
information regarding permissions, write to:
Pearson Education, Inc.
Rights and Contracts Department
501 Boylston Street, Suite 900
Boston, MA 02116
Fax: [phone]
ISBN 0-13-147749-8
Text printed in the United States on recycled paper at Courier in Westford Massachusetts.
Sixth printing, October 2008
Contents
Contents.....................................................................................................................iii
Welcome.....................................................................................................................xi
Is this book for you?...............................................................................................................................xi
How to use this book............................................................................................................................xii
Conventions used in this book............................................................................................................xii
Changes in this edition.........................................................................................................................xiii
Acknowledgments.....................................................................................................xv
Chapter 1. Quality technical information................................................................1
What is quality technical information?................................................................................................3
Relationships among the quality characteristics.................................................................4
Order of the groups.................................................................................................................4
Quality characteristics compared with elements and guidelines....................................5
Other possible quality characteristics of technical information.....................................6
Using the quality characteristics to develop quality technical information.................................7
Preparing to write: understanding users, tasks, and the product..................................8
Writing and rewriting...............................................................................................................9
Reviewing, testing, and evaluating technical information................................................10
Writing task, concept, and reference topics....................................................................................10
Establishing a unit of reuse....................................................................................................11
Restructuring technical information....................................................................................12
iii
Part 1. Easy to use...........................................................................................................15
Chapter 2. Task orientation.....................................................................................17
Write for the intended audience........................................................................................................19
Present information from the user’s point of view.........................................................................20
Indicate a practical reason for information......................................................................................23
Relate details to a task where appropriate........................................................................23
Provide only a necessary amount of conceptual information in task topics..............24
Focus on real tasks, not product functions......................................................................................27
Use headings that reveal the tasks.....................................................................................................31
Divide tasks into discrete subtasks....................................................................................................33
Provide clear, step-by-step instructions............................................................................................36
Make each step a clear action for users to take...............................................................36
Group steps for usability.......................................................................................................38
Clearly identify optional steps..............................................................................................41
Identify criteria at the beginning of conditional steps.....................................................43
In sum........................................................................................................................................................45
Chapter 3. Accuracy.................................................................................................47
Write information only when you understand it, and then verify it..........................................49
Keep up with technical changes..........................................................................................................53
Maintain consistency of all information about a subject................................................................58
Reuse information when possible........................................................................................60
Avoid introducing inconsistencies and eliminate those that you find..........................60
Use tools that automate checking for accuracy..............................................................................67
Check the accuracy of references to related information............................................................69
In sum........................................................................................................................................................72
Chapter 4. Completeness........................................................................................75
Cover all topics that support users’ tasks, and only those topics..............................................77
Cover each topic in just as much detail as users need..................................................................79
Include enough information..................................................................................................82
Include only necessary information.....................................................................................84
Use patterns of information to ensure proper coverage..............................................................90
Repeat information only when users will benefit from it..............................................................96
In sum........................................................................................................................................................99
iv
Developing Quality Technical Information
Contents
Part 2. Easy to understand........................................................................101
Chapter 5. Clarity...................................................................................................103
Focus on the meaning..........................................................................................................................105
Avoid ambiguity.....................................................................................................................................110
Use words with a clear meaning........................................................................................110
Avoid vague referents...........................................................................................................113
Place modifiers appropriately.............................................................................................114
Avoid long strings of nouns.................................................................................................116
Write positively.....................................................................................................................118
Make the syntax of sentences clear..................................................................................120
Keep elements short............................................................................................................................124
Remove roundabout expressions and needless repetition..........................................124
Choose direct words............................................................................................................127
Keep lists short......................................................................................................................129
Write cohesively...................................................................................................................................132
Present similar information in a similar way...................................................................................136
Use lists appropriately..........................................................................................................136
Segment information into tables........................................................................................139
Use technical terms only if they are necessary and appropriate...............................................141
Decide whether to use a term...........................................................................................141
Use terms consistently.........................................................................................................142
Define each term that is new to the intended audience.............................................................144
In sum......................................................................................................................................................146
Chapter 6. Concreteness.......................................................................................149
Choose examples that are appropriate for the audience and subject.....................................152
Consider the level and needs of users.............................................................................152
Use examples appropriately in conceptual, task, and reference information..........154
Use focused, realistic, accurate, up-to-date examples.................................................................160
Make examples easy to find...............................................................................................................162
Use visual cues to indicate where examples are............................................................162
Make examples part of the user interface.......................................................................163
Make clear where examples start and stop.....................................................................163
Make code examples easy to adapt..................................................................................................166
Use scenarios to illustrate tasks and to provide overviews.......................................................169
Set the context for examples and scenarios..................................................................................172
Relate unfamiliar information to familiar information..................................................................174
Use general language appropriately..................................................................................................176
In sum......................................................................................................................................................178
v
Chapter 7. Style......................................................................................................181
Use correct grammar..........................................................................................................................183
Check for sentence fragments...........................................................................................184
Correct pronoun problems................................................................................................185
Correct dangling modifiers..................................................................................................187
Use correct and consistent spelling.................................................................................................189
Use consistent and appropriate punctuation.................................................................................191
Write with the appropriate tone......................................................................................................193
Use an active style................................................................................................................................196
Use active voice.....................................................................................................................196
Use the present tense..........................................................................................................198
Use the appropriate mood.................................................................................................................199
Follow template designs and use boilerplate text.........................................................................200
Create and reuse templates................................................................................................200
Use boilerplate text to ensure inclusion of necessary information...........................201
Create and follow style guidelines....................................................................................................203
Provide practical and consistent highlighting...................................................................205
Present list items consistently............................................................................................207
Use unbiased language..........................................................................................................208
In sum......................................................................................................................................................211
Part 3. Easy to find.....................................................................................213
Chapter 8. Organization........................................................................................215
Organize information into discrete topics by type.......................................................................218
Organize tasks by order of use.........................................................................................................222
Organize topics for quick retrieval...................................................................................................225
Separate contextual information from other types of information..........................................228
Organize information consistently...................................................................................................232
Provide an appropriate number of subentries for each branch.................................................234
Emphasize main points; subordinate secondary points...............................................................236
Reveal how the pieces fit together...................................................................................................239
In sum......................................................................................................................................................243
Chapter 9. Retrievability........................................................................................245
Facilitate navigation and search.........................................................................................................247
Provide a complete and consistent index.......................................................................................249
Use an appropriate level of detail in the table of contents.........................................................254
Provide helpful entry points...............................................................................................................257
Link appropriately.................................................................................................................................260
Design helpful links..............................................................................................................................264
Ensure that a link describes the information that it links to.......................................264
vi
Developing Quality Technical Information
Contents
In similar links and cross-references, emphasize the text that is different...............265
Minimize the effort that is needed to reach related information...............................265
Avoid redundant links...........................................................................................................266
Make linked-to information easy to find in the target topic.......................................................268
In sum......................................................................................................................................................273
Chapter 10. Visual effectiveness............................................................................277
Use graphics that are meaningful and appropriate........................................................................279
Illustrate significant concepts..............................................................................................279
Avoid illustrating what is already visible...........................................................................280
Choose graphics that complement the text..................................................................................284
Use visual elements for emphasis.....................................................................................................288
Emphasize the appropriate information...........................................................................288
Ensure that your visual elements are not distracting....................................................292
Use visual elements logically and consistently...............................................................................295
Use a visually simple but distinct heading hierarchy......................................................295
Maintain consistent placement of document elements................................................297
Ensure that the look and feel of multimedia presentations is consistent.................301
Use icons and symbols consistently..................................................................................303
Balance the number and placement of visual elements...............................................................304
Use visual cues to help users find what they need.......................................................................307
Visually identify recurring alternatives or contexts.......................................................307
Ensure that visual cues are usable in all environments.................................................309
Ensure that textual elements are legible.........................................................................................311
Use a legible typeface and size...........................................................................................311
Ensure that the text fits in the available space................................................................315
Ensure that the contrast between text and background is adequate........................316
Use color and shading discreetly and appropriately.....................................................................318
Ensure that all users can access the information..........................................................................323
In sum......................................................................................................................................................325
vii
Part 4. Putting it all together....................................................................329
Chapter 11. Applying more than one quality characteristic..............................331
Applying quality characteristics to task information....................................................................332
Applying quality characteristics to conceptual information........................................................337
Applying quality characteristics to reference information..........................................................340
Applying quality characteristics to information for an international audience.......................344
Applying quality characteristics to information on the Web......................................................351
Revising technical information...........................................................................................................355
Chapter 12. Reviewing, testing, and evaluating technical information.............357
Inspecting technical information.......................................................................................................358
Reading and using the information....................................................................................358
Finding problems....................................................................................................................359
Reporting problems..............................................................................................................360
Testing information for usability........................................................................................................361
Prototyping.............................................................................................................................362
Testing outside a usability laboratory...............................................................................362
Testing in a usability laboratory..........................................................................................363
Testing technical information.............................................................................................................367
Using test tools......................................................................................................................368
Using test cases......................................................................................................................368
Testing the user interface....................................................................................................369
Editing and evaluating technical information..................................................................................370
Preparing to edit....................................................................................................................371
Getting an overview..............................................................................................................371
Reading and editing the information.................................................................................373
Looking for specific information........................................................................................376
Summarizing your findings...................................................................................................376
Conferring with the writer.................................................................................................378
Reviewing the visual elements...........................................................................................................379
Preparing to review...............................................................................................................380
Getting an overview..............................................................................................................380
Reviewing individual visual elements.................................................................................382
Summarizing your findings...................................................................................................383
Conferring with the editor or writer or both................................................................384
viii
Developing Quality Technical Information
Contents
Part 5. Appendixes.....................................................................................385
Appendix A. Quality checklist..............................................................................387
Appendix B. Who checks which quality characteristics?...................................391
Appendix C. Quality characteristics and elements............................................397
Looking at the quality characteristics..............................................................................................398
Looking at the elements.....................................................................................................................398
Resources and references.......................................................................................401
Easy to use.............................................................................................................................................401
Easy to understand...............................................................................................................................404
Easy to find.............................................................................................................................................407
Putting it all together...........................................................................................................................409
Glossary...................................................................................................................413
Index.........................................................................................................................425
ix