Developing Quality Technical Information: A Handbook for Writers and Editors, Third Edition

Table of contents

1. About This eBook
2. Title Page
3. Copyright Page
4. Contents
5. Preface
   1. About this book
   2. Is this book for you?
   3. Changes in this edition
6. Acknowledgments
7. About the authors
8. Part 1: Introduction
   1. Chapter 1. Technical information continues to evolve
      1. Embedded assistance
      2. The technical writer’s role today
      3. Redefining quality technical information
   2. Chapter 2. Developing quality technical information
      1. Preparing to write: understanding users, goals, and product tasks
      2. Writing and rewriting
      3. Reviewing, testing, and evaluating technical information
9. Part 2: Easy to use
   1. Chapter 3. Task orientation
      1. Write for the intended audience
      2. Present information from the users’ point of view
      3. Focus on users’ goals
      4. Indicate a practical reason for information
      5. Provide clear, step-by-step instructions
      6. Task orientation checklist
   2. Chapter 4. Accuracy
      1. Research before you write
      2. Verify the information that you write
      3. Maintain information currency
      4. Maintain consistency in all information about a subject
      5. Use tools that automate checking for accuracy
      6. Accuracy checklist
   3. Chapter 5. Completeness
      1. Make user interfaces self-documenting
      2. Apply a pattern for disclosing information
      3. Cover all subjects that support users’ goals and only those subjects
      4. Cover each subject in only as much detail as users need
      5. Repeat information only when users will benefit from it
      6. Completeness checklist
10. Part 3: Easy to understand
    1. Chapter 6. Clarity
       1. Focus on the meaning
       2. Eliminate wordiness
       3. Write coherently
       4. Avoid ambiguity
       5. Use technical terms consistently and appropriately
       6. Clarity checklist
    2. Chapter 7. Concreteness
       1. Consider the skill level and needs of users
       2. Use concreteness elements that are appropriate for the information type
       3. Use focused, realistic, and up-to-date concreteness elements
       4. Use scenarios to illustrate tasks and to provide overviews
       5. Make code examples and samples easy to use
       6. Set the context for examples and scenarios
       7. Use similes and analogies to relate unfamiliar information to familiar information
       8. Use specific language
       9. Concreteness checklist
    3. Chapter 8. Style
       1. Use active and passive voice appropriately
       2. Convey the right tone
       3. Avoid gender and cultural bias
       4. Spell terms consistently and correctly
       5. Use proper capitalization
       6. Use consistent and correct punctuation
       7. Apply consistent highlighting
       8. Make elements parallel
       9. Apply templates and reuse commonly used expressions
       10. Use consistent markup tagging
       11. Style checklist
11. Part 4: Easy to find
    1. Chapter 9. Organization
       1. Put information where users expect it
       2. Arrange elements to facilitate navigation
       3. Reveal how elements fit together
       4. Emphasize main points; subordinate secondary points
       5. Organization checklist
    2. Chapter 10. Retrievability
       1. Optimize for searching and browsing
       2. Guide users through the information
       3. Link appropriately
       4. Provide helpful entry points
       5. Retrievability checklist
    3. Chapter 11. Visual effectiveness
       1. Apply visual design practices to textual elements
       2. Use graphics that are meaningful and appropriate
       3. Apply a consistent visual style
       4. Use visual elements to help users find what they need
       5. Ensure that visual elements are accessible to all users
       6. Visual effectiveness checklist
12. Part 5: Putting it all together
    1. Chapter 12. Applying more than one quality characteristic
       1. Applying quality characteristics to progressively disclosed information
       2. Applying quality characteristics to information for an international audience
       3. Applying quality characteristics to topic-based information
    2. Chapter 13. Reviewing, testing, and evaluating technical information
       1. Reviewing technical information
       2. Testing information for usability
       3. Testing technical information
       4. Editing and evaluating technical information
       5. Reading and editing the information
       6. Reviewing the visual elements
13. Part 6: Appendixes
    1. Appendix A. Quality checklist
    2. Appendix B. Who checks which characteristics?
14. Glossary
15. Resources and references
    1. Easy to use
    2. Easy to understand
    3. Easy to find
    4. Putting it all together
16. Index