Preface    xvii
Acknowledgments    xix
About the authors    xxiii
Part 1. Introduction   1
Chapter 1. Technical information continues to evolve   3
Embedded assistance   4
Progressive disclosure of information   9
The technical writer’s role today   11
Redefining quality technical information   13
Chapter 2. Developing quality technical information   15
Preparing to write: understanding users, goals, and product tasks   16
Writing and rewriting   17
Reviewing, testing, and evaluating technical information   19
Part 2. Easy to use   21
Chapter 3. Task orientation   23
Write for the intended audience   25
Present information from the users’ point of view   27
Focus on users’ goals   32
Identify tasks that support users’ goals   33
Write user-oriented task topics, not function-oriented task topics   35
Avoid an unnecessary focus on product features   41
Indicate a practical reason for information   46
Provide clear, step-by-step instructions   49
Make each step a clear action for users to take   51
Group steps for usability   53
Clearly identify steps that are optional or conditional   58
Task orientation checklist   64
Chapter 4. Accuracy   67
Research before you write   69
Verify information that you write   74
Maintain information currency   79
Keep up with technical changes   79
Avoid writing information that will become outdated   82
Maintain consistency in all information about a subject   86
Reuse information when possible   86
Avoid introducing inconsistencies   88
Use tools that automate checking for accuracy   93
Accuracy checklist   96
Chapter 5. Completeness   99
Make user interfaces self-documenting   101
Apply a pattern for disclosing information   107
Cover all subjects that support users’ goals and only those subjects   115
Create an outline or topic model   115
Include only information based on user goals   118
Make sure concepts and reference topics support the goals   122
Cover each subject in only as much detail as users need   123
Provide appropriate detail for your users and their experience level   123
Include enough information   130
Include only necessary information   136
Repeat information only when users will benefit from it   141
Completeness checklist   148
Part 3. Easy to understand   151
Chapter 6. Clarity   153
Focus on the meaning   155
Eliminate wordiness   161
Write coherently   174
Avoid ambiguity   180
Use words as only one part of speech   180
Avoid empty words   183
Use words with a clear meaning   187
Write positively   189
Make the syntax of sentences clear   194
Use pronouns correctly   199
Place modifiers appropriately   201
Use technical terms consistently and appropriately   205
Decide whether to use a term   205
Use terms consistently   207
Define each term that is new to the intended audience   210
Clarity checklist   212
Chapter 7. Concreteness   215
Consider the skill level and needs of users   220
Use concreteness elements that are appropriate for the information type   223
Use focused, realistic, and up-to-date concreteness elements   240
Use scenarios to illustrate tasks and to provide overviews   243
Make code examples and samples easy to use   247
Set the context for examples and scenarios   251
Use similes and analogies to relate unfamiliar information to familiar information   253
Use specific language   256
Concreteness checklist   259
Chapter 8. Style   261
Use active and passive voice appropriately   263
Convey the right tone   267
Avoid gender and cultural bias   273
Spell terms consistently and correctly   276
Use proper capitalization   280
Use consistent and correct punctuation   284
Apply consistent highlighting   296
Make elements parallel   302
Apply templates and reuse commonly used expressions   305
Use consistent markup tagging   311
Style checklist   314
Part 4. Easy to find   317
Chapter 9. Organization   319
Put information where users expect it   322
Separate contextual information from other types of information   324
Separate contextual information into the appropriate type of embedded assistance   332
Separate noncontextual information into discrete topics by type   337
Arrange elements to facilitate navigation   345
Organize elements sequentially   350
Organize elements consistently   354
Reveal how elements fit together   360
Emphasize main points; subordinate secondary points   366
Organization checklist   376
Chapter 10. Retrievability   379
Optimize for searching and browsing   381
Use clear, descriptive titles   381
Use keywords effectively   384
Optimize the table of contents for scanning   389
Guide users through the information   394
Link appropriately   399
Link to essential information   400
Avoid redundant links   405
Use effective wording for links   409
Provide helpful entry points   413
Retrievability checklist   420
Chapter 11. Visual effectiveness   421
Apply visual design practices to textual elements   424
Use graphics that are meaningful and appropriate   431
Illustrate significant tasks and concepts   431
Make information interactive   441
Use screen captures judiciously   448
Apply a consistent visual style   460
Use visual elements to help users find what they need   467
Ensure that visual elements are accessible to all users   478
Visual effectiveness checklist   483
Part 5. Putting it all together   485
Chapter 12. Applying more than one quality characteristic   487
Applying quality characteristics to progressively disclosed information   488
Applying quality characteristics to information for an international audience   494
Applying quality characteristics to topic-based information   501
Chapter 13. Reviewing, testing, and evaluating technical information   515
Reviewing technical information   516
Testing information for usability   518
Testing technical information   524
Editing and evaluating technical information   527
Reading and editing the information   531
Reviewing the visual elements   536
Part 6. Appendixes   543
Appendix A. Quality checklist   545
Appendix B. Who checks which characteristics?   549
Glossary   555
Resources and references   565
Index   573
Â
Â
