You are previewing Developing Quality Technical Information: A Handbook for Writers and Editors, Third Edition.
O'Reilly logo
Developing Quality Technical Information: A Handbook for Writers and Editors, Third Edition

Book Description

The #1 Guide to Excellence in Technical Communication—Fully Updated for Embedded Assistance, Mobile, Search, Multimedia, and More

Direct from IBM’s own content design experts, this guide shows you how to design product interfaces and technical information that always place users front and center. This edition has been fully revised to help you consistently deliver the right content at the right time.

You’ll master today’s best practices to apply nine essential characteristics of high-quality technical information: accuracy, clarity, completeness, concreteness, organization, retrievability, style, task orientation, and visual effectiveness.

Coverage Includes

  • Advocating for users throughout the entire product development process

  • Delivering information in an ordered manner by following progressive disclosure techniques

  • Optimizing content so that users can find it from anywhere

  • Streamlining information for mobile delivery

  • Helping users right where they are

  • Whether you’re a writer, editor, information architect, user experience professional, or reviewer, this book shows you how to create great technical information, from the product design to the user interface, topics, and other media.

  • Thoroughly revised and updated

  • Extensive new coverage of self-documenting interfaces and embedded assistance

  • Updated practical guidelines and checklists

  • Hundreds of new examples

  • 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