Developing Quality Technical Information

1. Quality Technical Information. What is quality technical information? Quality characteristics compared with elements and guidelines. Other possible quality characteristics of technical information. How do I use the quality characteristics to develop quality technical information? Preparing to write: understanding users, tasks, and the product. Writing and rewriting. I. EASY TO USE. 2. Task Orientation. Write for the intended audience. Present information from the users point of view. Focus on real tasks, not product functions. Indicate a practical reason for information. Relate conceptual information to tasks where appropriate. Provide only the appropriate amount of conceptual information. Use titles and headings that reveal the tasks. In sum. 3. Accuracy. Write only information that you understand, and verify it. Run tools that automate accuracy checking. Keep up with changes in the product. Maintain consistency in all information on a given topic. Reuse information when possible. Manually synchronize related information that doesnt match. Check the accuracy of references to related information. In sum. 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. II. EASY TO UNDERSTAND. 5. Clarity. Focus on the meaning. Avoid ambiguity. Choose and use words with a clear meaning. Avoid vague referents. Place modifiers appropriately. Avoid long strings of nouns. Write positively. Keep elements short. Remove roundabout expressions and needless repetition. Choose direct words. Keep lists short. Write cohesively. Present similar topics 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. 6. Concreteness. Choose examples that are appropriate for the audience and topic. Use realistic, accurate, up-to-date examples. Make examples easy to find. Use scenarios to illustrate tasks and provide product overviews. Use code examples that users can easily adapt. Relate unfamiliar information to familiar information. In sum. 7. Style. Use correct grammar, spelling, and punctuation. Follow style guidelines. Provide practical and consistent highlighting. Present list items consistently. Use gender-neutral language. Use an active style. Use the imperative mood for instructions. Use appropriate and consistent tone. In sum. III. EASY TO FIND. 8. Organization. Organize guidance information sequentially. Organize reference information logically. Organize information consistently. Organize help into discrete topics and types. Emphasize main points, subordinate secondary points. Divide a topic only if it has at least two subtopics. Branch only when helpful to the user. Reveal how the pieces fit together. In sum. 9. Retrievability. Break up text into manageable chunks. Stock the index with entries that users expect. Make sure the index is complete and correct. Make linked-to information easy to find on the target help window or page. In introductory sections, reveal the order of topics to come. Use an appropriate level of detail in a table of contents. Make key terms easy to find. In sum. 10. Visual Effectiveness. Balance the amount and placement of visual elements. Use graphics that are meaningful and appropriate. Illustrate difficult concepts. Avoid illustrating what is already visible. Choose illustrations that complement the text. Present textual elements in a legible size and font. Use visual elements for emphasis. Use visual elements logically and consistently. Use color and shading discreetly and significantly. Use visual cues to help users find what they need. In sum. IV. PUTTING IT ALL TOGETHER. 11. Applying More Than One Quality Characteristic. Applying quality characteristics to guidance information. Applying quality characteristics to reference information. Applying quality characteristics to combined guidance and reference information. Revising technical information. 12. Reviewing and Evaluating Technical Information. Inspecting technical information. Testing information for usability. Editing and evaluating technical information. Prepare to edit. Get an overview. Read and edit the information. Look for information. Summarize your findings. Confer with the writer. Reviewing the visual elements. Prepare to review. Get an overview. Review individual graphic elements. Summarize your findings. Confer with the editor or writer. V. APPENDIXES, BIBLIOGRAPHY, AND GLOSSARY. 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. Appendix D. Words to Watch for Clarity. Intensifying words. Imprecise verbs. Words that can be hard to translate. Negative expressions. Roundabout expressions. Needless repetition. Words derived from Latin. Bibliography. General. Easy to Use. Easy to Understand. Easy to Find. Glossary. Index.