Developing quality technical information : a handbook for writers and editors /

Saved in:
Bibliographic Details
Edition:2nd ed.
Imprint:Upper Saddle River, N.J. : Prentice Hall PTR, c2004.
Description:xvi, 445 p. : ill. ; 25 cm.
Language:English
Subject:Technical writing.
Technical editing.
Technical editing.
Technical writing.
Format: Print Book
URL for this record:http://pi.lib.uchicago.edu/1001/cat/bib/5161621
Hidden Bibliographic Details
Other authors / contributors:Hargis, Gretchen.
ISBN:0131477498
Notes:At head of title: IBM Press.
Includes bibliographical references (p. 401-411) and index.
committed to retain 20170930 20421213 HathiTrust
Table of Contents:
  • Contents
  • Welcome
  • Is this book for you?
  • How to use this book
  • Conventions used in this book
  • Changes in this edition
  • Acknowledgments
  • Chapter 1.. Quality technical information
  • What is quality technical information?
  • Relationships among the quality characteristics
  • Order of the groups
  • Quality characteristics compared with elements and guidelines
  • Other possible quality characteristics of technical information
  • Using the quality characteristics to develop quality technical information
  • Preparing to write: understanding users, tasks, and the product
  • Writing and rewriting
  • Reviewing, testing, and evaluating technical information
  • Writing task, concept, and reference topics
  • Establishing a unit of reuse
  • Restructuring technical information
  • Part 1.. Easy to use
  • Chapter 2.. Task orientation
  • Write for the intended audience
  • Present information from the user's point of view
  • Indicate a practical reason for information
  • Relate details to a task where appropriate
  • Provide only a necessary amount of conceptual information in task topics
  • Focus on real tasks, not product functions
  • Use headings that reveal the tasks
  • Divide tasks into discrete subtasks
  • Provide clear, step-by-step instructions
  • Make each step a clear action for users to take
  • Group steps for usability
  • Clearly identify optional steps
  • Identify criteria at the beginning of conditional steps
  • In sum
  • Chapter 3.. Accuracy
  • Write information only when you understand it, and then verify it
  • Keep up with technical changes
  • Maintain consistency of all information about a subject
  • Reuse information when possible
  • Avoid introducing inconsistencies and eliminate those that you find
  • Use tools that automate checking for accuracy
  • Check the accuracy of references to related information
  • In sum
  • Chapter 4.. Completeness
  • Cover all topics that support users' tasks, and only those topics
  • Cover each topic in just as much detail as users need
  • Include enough information
  • Include only necessary information
  • Use patterns of information to ensure proper coverage
  • Repeat information only when users will benefit from it
  • In sum
  • Part 2.. Easy to understand
  • Chapter 5.. Clarity
  • Focus on the meaning
  • Avoid ambiguity
  • Use words with a clear meaning
  • Avoid vague referents
  • Place modifiers appropriately
  • Avoid long strings of nouns
  • Write positively
  • Make the syntax of sentences clear
  • Keep elements short
  • Remove roundabout expressions and needless repetition
  • Choose direct words
  • Keep lists short
  • Write cohesively
  • Present similar information in a similar way
  • Use lists appropriately
  • Segment information into tables
  • Use technical terms only if they are necessary and appropriate
  • Decide whether to use a term
  • Use terms consistently
  • Define each term that is new to the intended audience
  • In sum
  • Chapter 6.. Concreteness
  • Choose examples that are appropriate for the audience and subject
  • Consider the level and needs of users
  • Use examples appropriately in conceptual, task, and reference information
  • Use focused, realistic, accurate, up-to-date examples
  • Make examples easy to find
  • Use visual cues to indicate where examples are
  • Make examples part of the user interface
  • Make clear where examples start and stop
  • Make code examples easy to adapt
  • Use scenarios to illustrate tasks and to provide overviews
  • Set the context for examples and scenarios
  • Relate unfamiliar information to familiar information
  • Use general language appropriately
  • In sum
  • Chapter 7.. Style
  • Use correct grammar
  • Check for sentence fragments
  • Correct pronoun problems
  • Correct dangling modifiers
  • Use correct and consistent spelling
  • Use consistent and appropriate punctuation
  • Write with the appropriate tone
  • Use an active style
  • Use active voice
  • Use the present tense
  • Use the appropriate mood
  • Follow template designs and use boilerplate text
  • Create and reuse templates
  • Use boilerplate text to ensure inclusion of necessary information
  • Create and follow style guidelines
  • Provide practical and consistent highlighting
  • Present list items consistently
  • Use unbiased language
  • In sum
  • Part 3.. Easy to find
  • Chapter 8.. Organization
  • Organize information into discrete topics by type
  • Organize tasks by order of use
  • Organize topics for quick retrieval
  • Separate contextual information from other types of information
  • Organize information consistently
  • Provide an appropriate number of subentries for each branch
  • Emphasize main points; subordinate secondary points
  • Reveal how the pieces fit together
  • In sum
  • Chapter 9.. Retrievability
  • Facilitate navigation and search
  • Provide a complete and consistent index
  • Use an appropriate level of detail in the table of contents
  • Provide helpful entry points
  • Link appropriately
  • Design helpful links
  • Ensure that a link describes the information that it links to
  • In similar links and cross-references, emphasize the text that is different
  • Minimize the effort that is needed to reach related information
  • Avoid redundant links
  • Make linked-to information easy to find in the target topic
  • In sum
  • Chapter 10.. Visual effectiveness
  • Use graphics that are meaningful and appropriate
  • Illustrate significant concepts
  • Avoid illustrating what is already visible
  • Choose graphics that complement the text
  • Use visual elements for emphasis
  • Emphasize the appropriate information
  • Ensure that your visual elements are not distracting
  • Use visual elements logically and consistently
  • Use a visually simple but distinct heading hierarchy
  • Maintain consistent placement of document elements
  • Ensure that the look and feel of multimedia presentations is consistent
  • Use icons and symbols consistently
  • Balance the number and placement of visual elements
  • Use visual cues to help users find what they need
  • Visually identify recurring alternatives or contexts
  • Ensure that visual cues are usable in all environments
  • Ensure that textual elements are legible
  • Use a legible typeface and size
  • Ensure that the text fits in the available space
  • Ensure that the contrast between text and background is adequate
  • Use color and shading discreetly and appropriately
  • Ensure that all users can access the information
  • In sum
  • Part 4.. Putting it all together
  • Chapter 11.. Applying more than one quality characteristic
  • Applying quality characteristics to task information
  • Applying quality characteristics to conceptual information
  • Applying quality characteristics to reference information
  • Applying quality characteristics to information for an international audience
  • Applying quality characteristics to information on the Web
  • Revising technical information
  • Chapter 12.. Reviewing, testing, and evaluating technical information
  • Inspecting technical information
  • Reading and using the information
  • Finding problems
  • Reporting problems
  • Testing information for usability
  • Prototyping
  • Testing outside a usability laboratory
  • Testing in a usability laboratory
  • Testing technical information
  • Using test tools
  • Using test cases
  • Testing the user interface
  • Editing and evaluating technical information
  • Preparing to edit
  • Getting an overview
  • Reading and editing the information
  • Looking for specific information
  • Summarizing your findings
  • Conferring with the writer
  • Reviewing the visual elements
  • Preparing to review
  • Getting an overview
  • Reviewing individual visual elements
  • Summarizing your findings
  • Conferring with the editor or writer or both
  • Part 5.. Appendixes
  • Appendix A.. Quality checklist
  • Appendix B.. Who checks which quality characteristics?
  • Appendix C.. Quality characteristics and elements
  • Looking at the quality characteristics
  • Looking at the elements
  • Resources and references
  • Easy to use
  • Easy to understand
  • Easy to find
  • Putting it all together
  • Glossary
  • Index