Contents
Chapter 1. Quality technical information
What is quality technical information?
Relationships among the quality characteristics
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
Reviewing, testing, and evaluating technical information
Writing task, concept, and reference topics
Restructuring technical information
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
Clearly identify optional steps
Identify criteria at the beginning of conditional steps
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
Cover all topics that support users' tasks, and only those topics
Cover each topic in just as much detail as users need
Include only necessary information
Use patterns of information to ensure proper coverage
Repeat information only when users will benefit from it
Use words with a clear meaning
Make the syntax of sentences clear
Remove roundabout expressions and needless repetition
Present similar information in a similar way
Segment information into tables
Use technical terms only if they are necessary and appropriate
Define each term that is new to the intended audience
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
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
Use correct and consistent spelling
Use consistent and appropriate punctuation
Write with the appropriate tone
Follow template designs and use boilerplate text
Use boilerplate text to ensure inclusion of necessary information
Create and follow style guidelines
Provide practical and consistent highlighting
Present list items consistently
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
Facilitate navigation and search
Provide a complete and consistent index
Use an appropriate level of detail in the table of contents
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
Make linked-to information easy to find in the target topic
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
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
Testing information for usability
Testing outside a usability laboratory
Testing in a usability laboratory
Editing and evaluating technical information
Reading and editing the information
Looking for specific information
Reviewing individual visual elements
Conferring with the editor or writer or both
Appendix B. Who checks which quality characteristics?
Appendix C. Quality characteristics and elements