Home > Store

Developing Quality Technical Information: A Handbook for Writers and Editors, 2nd Edition

Register your product to gain access to bonus material or receive a coupon.

  • Description
  • Sample Content

"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!



Online Sample Chapter

Task-Oriented Writing for Techies

Sample Chapter(s)

Download the Sample Chapter related to this title.

Table of Contents



Welcome.

Is this book for you? How to use this book. Conventions used in this book. Changes in this edition.



Acknowledgments.


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.

I. EASY TO USE.

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.

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.

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. 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.

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.

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.

III. EASY TO FIND.

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.

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.

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.

IV. PUTTING IT ALL TOGETHER.

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 Web351 Revising technical information.

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.

V. 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.

 
Best Value

Book + eBook Bundle  $107.98  $61.79

Book Price: $44.99
eBook Price: $16.80

Add To Cart

This book includes Instant Online Access with Safari and free shipping!

Instant Online Access with Safari Books Online

With your book purchase you are entitled to free, instant online access to that book on Safari Books Online for 45 days. After you've completed your purchase, you will receive instructions on how to log into Safari Books Online. If you do not want to receive online access to the book, simply uncheck the box for Instant Online Access in your cart.

Add To Cart

Book  $59.99  $44.99

Usually ships in 24 hours.

This book includes Instant Online Access with Safari and free shipping!

Instant Online Access with Safari Books Online

With your book purchase you are entitled to free, instant online access to that book on Safari Books Online for 45 days. After you've completed your purchase, you will receive instructions on how to log into Safari Books Online. If you do not want to receive online access to the book, simply uncheck the box for Instant Online Access in your cart.

Add To Cart

eBook  $47.99  $35.99

About this eBook

Requires the free Adobe® Reader® software.

Download after purchase.

Information Before downloading this DRM-encrypted Adobe® Reader® PDF file, be sure to:


  • Install Adobe Reader 6.x, 7.x, or the free Adobe Digital Editions software on your machine. Adobe Reader and Adobe Digital Editions software only works for Macintosh and Windows. The Linux and Unix versions of Adobe Reader do not have the plug-ins required to decrypt the eBook.
  • Activate the DRM through the Adobe Reader software or at Adobe's DRM Activator site.
  • Follow the procedures as specified by Adobe.
  • Visit our eBook FAQ page for more information.
Safari Books Online

What is this?

Online access to books, videos, and tutorials from Addison Wesley, Prentice Hall, Cisco Press, IBM Press, O'Reilly Media and others - starting as low as $22.99. Learn more and start a free trial.

Start Reading Online

Other Things You Might Like

Inkscape: Guide to a Vector Drawing Program, 3rd Edition
Inkscape: Guide to a Vector Drawing Program, 3rd Edition
By Tavmjong Bah
Nov 6, 2009
$29.99
Inkscape: Guide to a Vector Drawing Program (Digital Short Cut), 3rd Edition
Inkscape: Guide to a Vector Drawing Program (Digital Short Cut), 3rd Edition
By Tavmjong Bah
Oct 20, 2009
$19.99
Unicode Standard, Version 5.0, The, 5th Edition
Unicode Standard, Version 5.0, The, 5th Edition
By The Unicode Consortium
Nov 9, 2006
$52.49
Informit Network