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

Hardcover (Print)
Buy New
Buy New from BN.com
$36.19
Buy Used
Buy Used from BN.com
$35.29
(Save 41%)
Item is in good condition but packaging may have signs of shelf wear/aging or torn packaging.
Condition: Used – Good details
Used and New from Other Sellers
Used and New from Other Sellers
from $12.42
Usually ships in 1-2 business days
(Save 79%)
Other sellers (Hardcover)
  • All (21) from $12.42   
  • New (10) from $31.19   
  • Used (11) from $12.42   

Overview

Writing That Works

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
  • 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
Read More Show Less

Editorial Reviews

Booknews
This practical guide developed by IBM software documentation experts presents the basics of conveying quality technical information: from writing from the intended audience's point of view, to editing the text and visual elements. Includes a glossary, quality checklists, red flag words, and bibliography. Annotation c. by Book News, Inc., Portland, Or.
Read More Show Less

Product Details

  • ISBN-13: 9780131477490
  • Publisher: IBM Press
  • Publication date: 4/28/2004
  • Series: IBM Press Series--Information Management
  • Edition description: Second
  • Edition number: 2
  • Pages: 448
  • Sales rank: 1,169,770
  • Product dimensions: 7.10 (w) x 9.40 (h) x 1.30 (d)

Meet the Author

The authors have served on the Editing Council at IBM Silicon Valley Laboratory in San Jose, California, an organization dedicated to excellence in technical information. Gretchen Hargis is a technical manager at IBM for a group that provides user assistance and user-centered design for application development tools. She was a technical editor and writer and a pioneer of IBM Darwin Information Typing Architecture (DITA). Michelle Carey is a technical writer at IBM and a technical writing instructor at University of California Santa Cruz Extension. She is an expert on topic-based information systems and on writing for international audiences. Ann Kilty Hernandez is a technical editor at IBM and has been a technical writer, manager, and marketing specialist. She was a co-author of An Introduction to DB2 for OS/390 and contributed to its next edition, The Official Guide to DB2 UDB for z/OS. Polly Hughes, now retired from IBM, worked as a visual designer for technical information and software interfaces and as a technical writer. Deirdre Longo is a technical editor and writer at IBM who edits product interfaces and writes customer information, mostly for content management products. Shannon Rouiller is a technical editor at IBM who has written and edited topicbased information systems, books, contextual help, wizards, and interfaces for products that are marketed worldwide. She co-authored Designing Effective Wizards. Elizabeth Wilde is a technical editor at IBM and a leader in developing quality metrics and quality assurance processes for technical documentation. She also educates writers and editors throughout IBM on developing user-centered information.

Read More Show Less

Read an Excerpt

PREFACE: Welcome!

Many books on technical writing tell you how to develop different parts of technical information, such as headings, lists, tables, and indexes. Instead, we organized this book to tell you how to apply quality characteristics that, in our experience, make technical information easy to use, easy to understand, and easy to find. We hope you will find our approach useful and comprehensive-and we hope you will find the information in this book easy to use, easy to understand, and easy to find!


Is this book for you?

If you are a writer or reviewer of technical information-yes! If you write or review software information, this book may be of even more interest to you because the examples in it come from the domain of software. However, the quality characteristics and guidelines are universal to all information.


Reviewers can be any of the many people who are involved in developing technical information:

  • Writers
  • Editors
  • Graphic designers
  • Human factors engineers
  • Product developers and testers
  • Customer service personnel
  • Customers (perhaps as early users)
  • Managers

    In general, this book assumes that you know the basics of good grammar, punctuation, and spelling as they apply to writing. It does not assume that you are familiar with what makes technical information good or bad.


    How to use this book

    You can use the book in any of several ways:

  • Read the book from start to finish.
  • Read about the particular quality characteristic or guideline thatinterests you.
  • Use the checklists at the end of each chapter and "Quality Checklist" on page 269 to evaluate a piece of technical information against the quality characteristics.
  • Use "Who Checks Which Quality Characteristics?" on page 273 to see what areas you as a reviewer need to check, and read those sections.

    Whatever your role in developing technical information, we hope that you'll use this information to build these quality characteristics into the information that you work on.

    Changes in this edition

    The first and second editions were published in 1984 and 1986 for use mainly by developers of information for IBM software products. This edition is published for more general use and takes into account these changes in technical information:

  • Online information (such as help, tutorials, and documents) is often more important than printed information in the documentation of software.
  • Online information has become more integrated with the product user interface, through forms such as cue cards and wizards.

    As a result of comments from customers and editors, we have:

  • Added two quality characteristics: concreteness and style

    Feedback from users showed that, to them, examples and scenarios are not only very important, but also generally lacking or poorly handled in computer information. The first edition treated examples as part of clarity, but clarity has many other aspects as well. In this edition we have added concreteness as the quality characteristic that focuses especially on examples and scenarios.


    In the first edition, style considerations were spread across accuracy, clarity, and visual communication. We decided that style needs its own focus.


  • Renamed two quality characteristics

    The earlier name "entry points" has become "retrievability," and "visual communication" has become "visual effectiveness."

    In addition, we have reorganized the book into parts and added several sections:

  • Introduction to help define terms and set the context for the information
  • Chapters 11 and 12, which treat more than one quality characteristic
  • Annotated bibliography
  • Glossary of terms used in this book
  • Index

    The technical editors at IBM's Santa Teresa Laboratory use these quality characteristics to assess the quality of the information they edit. In this edition, we have revised some guidelines and added more examples to ensure coverage of the kinds of common errors found every day.


    Gretchen Hargis Ann Kilty Hernandez Polly Hughes Jim Ramaker Shannon Rouiller Elizabeth Wilde
Read More Show Less

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.

Read More Show Less

Preface

Many books about technical writing tell you how to develop different parts of technical information, such as headings, lists, tables, and indexes.  Instead, we organized this book to tell you how to apply quality characteristics that, in our experience, make technical information easy to use, easy to understand, and easy to find. We hope you will find our approach useful and comprehensive-and we hope that you will find the information in this book easy to use, easy to understand, and easy to find!  Is this book for you?

If you are a writer, editor, or reviewer of technical information-yes! If you write, edit, or review software information, this book might be of even more interest to you because most of the examples in it come from the domain of software. However, the quality characteristics and guidelines apply to all technical information.

Reviewers can be any of the many people who are involved in developing technical information:

Writers

Editors

Visual designers

Human factors engineers

Product developers and testers

Customer service personnel

Customers (perhaps as early users)

Managers

 

In general, this book assumes that you know the basics of good grammar, punctuation, and spelling as they apply to writing. It does not assume that you are familiar with what makes technical information good or bad.

How to use this book

You can use the book in any of several ways, such as:

Read the book from start to finish.

Read about the particular quality characteristic or guideline that interests you.

Read Chapter 11, “Applying more than one quality characteristic 1,” on page 331 to see how the quality characteristics interact, and then read the particular chapters that fit what you’re working on.  Use the checklists at the end of each chapter and Appendix A, “Quality checklist,” on page 387 to evaluate a piece of technical information by using the quality characteristics.

Use Appendix B, “Who checks which quality characteristics?,” on page 391 to see what areas you as a reviewer need to check, and read those sections.  Whatever your role in developing technical information, we hope that you’ll use this information to build these quality characteristics into the information that you work on.

Conventions used in this book

Nine of the twelve chapters in this book deal with the quality characteristics, one per chapter. Each of these chapters has a series of guidelines about how to enhance the particular quality characteristic.  Within each guideline, this book uses examples, usually in pairs of an original passage such as you might see in technical information and a revision that demonstrates the application of the guideline. Some passages go through more than one revision. The descriptions of the guideline and of the examples aim to help you understand and implement the guideline.  In addition, each of the nine chapters ends with a checklist. This checklist indicates the items to look for when you evaluate a piece of technical information by using the guidelines for the particular quality characteristic.

Changes in this edition

The basic organization of the book and the quality characteristics remain the same. However, within each quality characteristic, we have added, reworded, deleted, or moved some guidelines and subguidelines, and we have updated many examples. For example, the following guidelines are among those that we added:

“Organize information into discrete topics by type.” (Organization chapter)

“Facilitate navigation and search.” (Retrievability chapter) “Ensure that all users can access the information.” (Visual effectiveness chapter)

These changes resulted from several developments in technical communication:

Greater emphasis on topic-based information and single source Internationalization of information and increased delivery of technical information on the Web The need to make technical information accessible to people with disabilities such as blindness and deafness As with earlier developments in this field during the 20 years that these quality characteristics have been in use, the characteristics have been able to absorb the changes. This framework continues to apply to the information that we are called on to provide today.

We hope that you find this book useful in improving the quality of the information that you develop.

Gretchen Hargis

Michelle Carey

Ann Kilty Hernandez

Polly Hughes

Deirdre Longo

Shannon Rouiller

Elizabeth Wilde

Read More Show Less

Introduction

Many books about technical writing tell you how to develop different parts of technical information, such as headings, lists, tables, and indexes. Instead, we organized this book to tell you how to apply quality characteristics that, in our experience, make technical information easy to use, easy to understand, and easy to find. We hope you will find our approach useful and comprehensive--and we hope that you will find the information in this book easy to use, easy to understand, and easy to find!

Is this book for you?

If you are a writer, editor, or reviewer of technical information--yes! If you write, edit, or review software information, this book might be of even more interest to you because most of the examples in it come from the domain of software. However, the quality characteristics and guidelines apply to all technical information.

Reviewers can be any of the many people who are involved in developing technical information:

Writers
Editors
Visual designers
Human factors engineers
Product developers and testers
Customer service personnel
Customers (perhaps as early users)
Managers

In general, this book assumes that you know the basics of good grammar, punctuation, and spelling as they apply to writing. It does not assume that you are familiar with what makes technical information good or bad.

How to use this book

You can use the book in any of several ways, such as:

Read the book from start to finish.

Read about the particular quality characteristic or guideline that interests you.

Read Chapter 11, “Applying more than one quality characteristic 1,” on page 331 to see how the quality characteristics interact, and then read the particular chapters that fit what you're working on.

Use the checklists at the end of each chapter and Appendix A, “Quality checklist,” on page 387 to evaluate a piece of technical information by using the quality characteristics.

Use Appendix B, “Who checks which quality characteristics?,” on page 391 to see what areas you as a reviewer need to check, and read those sections.

Whatever your role in developing technical information, we hope that you'll use this information to build these quality characteristics into the information that you work on.

Conventions used in this book

Nine of the twelve chapters in this book deal with the quality characteristics, one per chapter. Each of these chapters has a series of guidelines about how to enhance the particular quality characteristic.

Within each guideline, this book uses examples, usually in pairs of an original passage such as you might see in technical information and a revision that demonstrates the application of the guideline. Some passages go through more than one revision. The descriptions of the guideline and of the examples aim to help you understand and implement the guideline.

In addition, each of the nine chapters ends with a checklist. This checklist indicates the items to look for when you evaluate a piece of technical information by using the guidelines for the particular quality characteristic.

Changes in this edition

The basic organization of the book and the quality characteristics remain the same. However, within each quality characteristic, we have added, reworded, deleted, or moved some guidelines and subguidelines, and we have updated many examples. For example, the following guidelines are among those that we added:

“Organize information into discrete topics by type.” (Organization chapter)

“Facilitate navigation and search.” (Retrievability chapter)

“Ensure that all users can access the information.” (Visual effectiveness chapter)

These changes resulted from several developments in technical communication:

Greater emphasis on topic-based information and single source

Internationalization of information and increased delivery of technical information on the Web

The need to make technical information accessible to people with disabilities such as blindness and deafness

As with earlier developments in this field during the 20 years that these quality characteristics have been in use, the characteristics have been able to absorb the changes. This framework continues to apply to the information that we are called on to provide today.

We hope that you find this book useful in improving the quality of the information that you develop.

Gretchen Hargis
Michelle Carey
Ann Kilty Hernandez
Polly Hughes
Deirdre Longo
Shannon Rouiller
Elizabeth Wilde



Read More Show Less

Customer Reviews

Be the first to write a review
( 0 )
Rating Distribution

5 Star

(0)

4 Star

(0)

3 Star

(0)

2 Star

(0)

1 Star

(0)

Your Rating:

Your Name: Create a Pen Name or

Barnes & Noble.com Review Rules

Our reader reviews allow you to share your comments on titles you liked, or didn't, with others. By submitting an online review, you are representing to Barnes & Noble.com that all information contained in your review is original and accurate in all respects, and that the submission of such content by you and the posting of such content by Barnes & Noble.com does not and will not violate the rights of any third party. Please follow the rules below to help ensure that your review can be posted.

Reviews by Our Customers Under the Age of 13

We highly value and respect everyone's opinion concerning the titles we offer. However, we cannot allow persons under the age of 13 to have accounts at BN.com or to post customer reviews. Please see our Terms of Use for more details.

What to exclude from your review:

Please do not write about reviews, commentary, or information posted on the product page. If you see any errors in the information on the product page, please send us an email.

Reviews should not contain any of the following:

  • - HTML tags, profanity, obscenities, vulgarities, or comments that defame anyone
  • - Time-sensitive information such as tour dates, signings, lectures, etc.
  • - Single-word reviews. Other people will read your review to discover why you liked or didn't like the title. Be descriptive.
  • - Comments focusing on the author or that may ruin the ending for others
  • - Phone numbers, addresses, URLs
  • - Pricing and availability information or alternative ordering information
  • - Advertisements or commercial solicitation

Reminder:

  • - By submitting a review, you grant to Barnes & Noble.com and its sublicensees the royalty-free, perpetual, irrevocable right and license to use the review in accordance with the Barnes & Noble.com Terms of Use.
  • - Barnes & Noble.com reserves the right not to post any review -- particularly those that do not follow the terms and conditions of these Rules. Barnes & Noble.com also reserves the right to remove any review at any time without notice.
  • - See Terms of Use for other conditions and disclaimers.
Search for Products You'd Like to Recommend

Recommend other products that relate to your review. Just search for them below and share!

Create a Pen Name

Your Pen Name is your unique identity on BN.com. It will appear on the reviews you write and other website activities. Your Pen Name cannot be edited, changed or deleted once submitted.

 
Your Pen Name can be any combination of alphanumeric characters (plus - and _), and must be at least two characters long.

Continue Anonymously
Sort by: Showing all of 2 Customer Reviews
  • Anonymous

    Posted June 5, 2004

    Well argued, with good examples

    Reading this new edition, I was quite impressed by the practical nature of its suggestions, which are reinforced by good choices of example texts that are then revised and improved, in accordance with those suggestions. But it struck me that there is one logical subdivision of the book, which the authors may not necessarily have intended. It cleaves well into two portions. One deals with the timeless nature of writing clear, non-fiction text; totally independent of any computers. For example, it includes Part 2 of the book, entitled 'Easy to understand', which spans 3 chapters, 'Clarity', 'Concreteness' and 'Style'. Even from the single word titles, you could guess that they are of this ilk. In contrast, the other portion of the book relates more to a computer and browser oriented presentation. Both portions are well put. But the authors and the publisher may have sold themselves short. The first portion, with minor tweaks, could be useful enough as a standalone text. But to a far broader audience than technical writers. It could be directed at the high school or undergraduate level, for a class on non-fiction writing. In my high school, we never had guidelines as cogently argued as this. I could have used it then. So perhaps could you. Thus, the pity may be that most who might benefit from the book will never chance to encounter it.

    0 out of 1 people found this review helpful.

    Was this review helpful? Yes  No   Report this review
  • Anonymous

    Posted December 9, 2008

    No text was provided for this review.

Sort by: Showing all of 2 Customer Reviews

If you find inappropriate content, please report it to Barnes & Noble
Why is this product inappropriate?
Comments (optional)