| |
| |
| Contents | |
| |
| |
| Welcome | |
| |
| |
| Is this book for you? | |
| |
| |
| How to use this book | |
| |
| |
| Conventions used in this book | |
| |
| |
| Changes in this edition | |
| |
| |
| Acknowledgments | |
| |
| |
| |
| 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 | |
| |
| |
| |
| Easy to use | |
| |
| |
| |
| 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 | |
| |
| |
| |
| 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 | |
| |
| |
| |
| 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 | |
| |
| |
| |
| Easy to understand | |
| |
| |
| |
| 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 | |
| |
| |
| |
| 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 | |
| |
| |
| |
| 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 | |
| |
| |
| |
| Easy to find | |
| |
| |
| |
| 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 | |
| |
| |
| |
| 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 | |
| |
| |
| |
| 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 | |
| |
| |
| |
| Putting it all together | |
| |
| |
| |
| 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 | |
| |
| |
| |
| 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 | |
| |
| |
| |
| Appendixes | |
| |
| |
| |
| Quality checklist | |
| |
| |
| |
| Who checks which quality characteristics? | |
| |
| |
| |
| 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 | |