Developing quality technical information : a handbook for writers and editors

Format:

Book

Author/Creator:

Hargis, Gretchen, author.

Contributor:

Hargis, Gretchen, Contributor.

Safari Tech Books Online.

Series:

IBM Press series--information management

IBM Press series--information management Developing quality technical information

Language:

English

Subjects (All):

Technical writing.

Technical editing.

Physical Description:

1 online resource (xvi, 445 p. ) ill. ;

Edition:

2nd edition

Place of Publication:

[Place of publication not identified] Prentice Hall Professional Technical Reference 2004

Language Note:

English

System Details:

text file

Summary:

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

Contents:

Cover

Contents

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?

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

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

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

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

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

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

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

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

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

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.

Notes:

Bibliographic Level Mode of Issuance: Monograph

Includes bibliographical references (p. 401-411) and index.

Description based on publisher supplied metadata and other sources.

ISBN:

9786612431654

9781282431652

128243165X

9780137034574

0137034571

OCLC:

1027151875