'The examples are excellent--right on target and easy to understand and adapt. Even those who don't adopt the entire procedure can profit from the parts, but the greatest value will flow to those who adopt the whole.' --Carolyn Mulford, senior writer and editor of Writing That Works
'This is also a book that students can keep for their professional libraries because it will increase in its value to them after they leave class and face real life experiences on the job. It is plain enough for them to understand while they are learning, and at the same time comprehensive enough to support them as professionals.' --Elizabeth Boling, Instructional Systems Technology, Indiana University
'It practices what it preaches. Its guidelines are understandable and appropriate; its examples clear. It contains exactly what writers and editors need to know. It is the book that I would have written.' --Cynthia E. Spellman, Unisys
The #1 guide to excellence in documentation--now completely updated! A systematic, proven approach to creating great documentation
Thoroughly revised and updated
More practical examples
More coverage of topic-based information, search, and internationalization
Direct from IBM's own documentation experts, this is the definitive guide to developing outstanding technical documentation--for the Web and for print. Using extensive before-and-after examples, illustrations, and checklists, the authors show exactly how to create documentation that's easy to find, understand, and use. This edition includes extensive new coverage of topic-based information, simplifying search and retrievability, internationalization, visual effectiveness, and much more.
Coverage includes:
Focusing on the tasks and topics users care about most
Saying more with fewer words
Using organization and other means to deliver faster access to information
Presenting information in more visually inviting ways
Improving the effectiveness of your review process
Learning from example: sample text, screen captures, illustrations, tables, and much more
Whether you're a writer, editor, designer, or reviewer, if you want to create great documentation, this book shows you how!
Table of Contents:
Copyright
IBM Press Series-Information Management
On Demand Computing Books
DB2 Books
More Books from IBM Press
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?
Using the quality characteristics to develop quality technical information
Writing task, concept, and reference topics
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
Focus on real tasks, not product functions
Use headings that reveal the tasks
Divide tasks into discrete subtasks
Provide clear, step-by-step instructions
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
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
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
Keep elements short
Write cohesively
Present similar information in a similar way
Use technical terms only if they are necessary and appropriate
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
Use focused, realistic, accurate, up-to-date examples
Make examples easy to find
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
Use correct and consistent spelling
Use consistent and appropriate punctuation
Write with the appropriate tone
Use an active style
Use the appropriate mood
Follow template designs and use boilerplate text
Create and follow style guidelines
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
Make linked-to information easy to find in the target topic
In sum
Chapter 10.
Visual effectiveness
Use graphics that are meaningful and appropriate
Choose graphics that complement the text
Use visual elements for emphasis
Use visual elements logically and consistently
Balance the number and placement of visual elements
Use visual cues to help users find what they need
Ensure that textual elements are legible
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
Testing information for usability
Testing technical information
Editing and evaluating technical information
Reviewing the visual elements
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
