Developing Quality Technical Information

Michelle Carey / Moira McFadden Lanyi / Deirdre Longo / Eric Radzinski / Shannon Rouiller / Elizabeth Wilde  
Total pages
June 2014
Related Titles

Product detail

Product Price CHF Available  
Developing Quality Technical Information
55.40 approx. 7-9 days


Drawing on IBM's unsurpassed technical communications experience, readers discover today's best practices for meeting nine quality characteristics: accuracy, clarity, completeness, concreteness, organization, retrievability, style, task orientation, and visual effectiveness. Packed with guidelines, checklists, and before-and-after examples, Developing Quality Technical Information, Third Edition is an indispensable resource for the future of technical communication.


  • Reflects the changing and growing role of technical communicators in designing more usable products and embedding the right help at the right time, exactly where users need it
  • Brings together IBM's proven guidelines and checklists for creating exceptionally effective content
  • Helps you meet 9 core quality characteristics: accuracy, clarity, completeness, concreteness, organization, retrievability, style, task orientation, and visual effectiveness
  • Extensive "before-and-after" examples show how to avoid or fix problems

New to this Edition

The previous (second) edition emphasizes topic-based writing. In the new third edition, the authors address the changing role of technical communicators as core members of user interface design teams. They emphasize guidelines covering the full range of content that technical communicators are now responsible for, including content embedded in a product's user interface. These guidelines establish breakthrough best practices, and are supported with many new before-and-after examples.

Table of Contents

Preface xvii

Acknowledgments xix

About the authors xxiii

Part 1. Introduction 1

Chapter 1. Technical information continues to evolve 3

Embedded assistance 4

Progressive disclosure of information 9

The technical writer’s role today 11

Redefining quality technical information 13

Chapter 2. Developing quality technical information 15

Preparing to write: understanding users, goals, and product tasks 16

Writing and rewriting 17

Reviewing, testing, and evaluating technical information 19

Part 2. Easy to use 21

Chapter 3. Task orientation 23

Write for the intended audience 25

Present information from the users’ point of view 27

Focus on users’ goals 32

Identify tasks that support users’ goals 33

Write user-oriented task topics, not function-oriented task topics 35

Avoid an unnecessary focus on product features 41

Indicate a practical reason for information 46

Provide clear, step-by-step instructions 49

Make each step a clear action for users to take 51

Group steps for usability 53

Clearly identify steps that are optional or conditional 58

Task orientation checklist 64

Chapter 4. Accuracy 67

Research before you write 69

Verify information that you write 74

Maintain information currency 79

Keep up with technical changes 79

Avoid writing information that will become outdated 82

Maintain consistency in all information about a subject 86

Reuse information when possible 86

Avoid introducing inconsistencies 88

Use tools that automate checking for accuracy 93

Accuracy checklist 96

Chapter 5. Completeness 99

Make user interfaces self-documenting 101

Apply a pattern for disclosing information 107

Cover all subjects that support users’ goals and only those subjects 115

Create an outline or topic model 115

Include only information based on user goals 118

Make sure concepts and reference topics support the goals 122

Cover each subject in only as much detail as users need 123

Provide appropriate detail for your users and their experience level 123

Include enough information 130

Include only necessary information 136

Repeat information only when users will benefit from it 141

Completeness checklist 148

Part 3. Easy to understand 151

Chapter 6. Clarity 153

Focus on the meaning 155

Eliminate wordiness 161

Write coherently 174

Avoid ambiguity 180

Use words as only one part of speech 180

Avoid empty words 183

Use words with a clear meaning 187

Write positively 189

Make the syntax of sentences clear 194

Use pronouns correctly 199

Place modifiers appropriately 201

Use technical terms consistently and appropriately 205

Decide whether to use a term 205

Use terms consistently 207

Define each term that is new to the intended audience 210

Clarity checklist 212

Chapter 7. Concreteness 215

Consider the skill level and needs of users 220

Use concreteness elements that are appropriate for the information type 223

Use focused, realistic, and up-to-date concreteness elements 240

Use scenarios to illustrate tasks and to provide overviews 243

Make code examples and samples easy to use 247

Set the context for examples and scenarios 251

Use similes and analogies to relate unfamiliar information to familiar information 253

Use specific language 256

Concreteness checklist 259

Chapter 8. Style 261

Use active and passive voice appropriately 263

Convey the right tone 267

Avoid gender and cultural bias 273

Spell terms consistently and correctly 276

Use proper capitalization 280

Use consistent and correct punctuation 284

Apply consistent highlighting 296

Make elements parallel 302

Apply templates and reuse commonly used expressions 305

Use consistent markup tagging 311

Style checklist 314

Part 4. Easy to find 317

Chapter 9. Organization 319

Put information where users expect it 322

Separate contextual information from other types of information 324

Separate contextual information into the appropriate type of embedded assistance 332

Separate noncontextual information into discrete topics by type 337

Arrange elements to facilitate navigation 345

Organize elements sequentially 350

Organize elements consistently 354

Reveal how elements fit together 360

Emphasize main points; subordinate secondary points 366

Organization checklist 376

Chapter 10. Retrievability 379

Optimize for searching and browsing 381

Use clear, descriptive titles 381

Use keywords effectively 384

Optimize the table of contents for scanning 389

Guide users through the information 394

Link appropriately 399

Link to essential information 400

Avoid redundant links 405

Use effective wording for links 409

Provide helpful entry points 413

Retrievability checklist 420

Chapter 11. Visual effectiveness 421

Apply visual design practices to textual elements 424

Use graphics that are meaningful and appropriate 431

Illustrate significant tasks and concepts 431

Make information interactive 441

Use screen captures judiciously 448

Apply a consistent visual style 460

Use visual elements to help users find what they need 467

Ensure that visual elements are accessible to all users 478

Visual effectiveness checklist 483

Part 5. Putting it all together 485

Chapter 12. Applying more than one quality characteristic 487

Applying quality characteristics to progressively disclosed information 488

Applying quality characteristics to information for an international audience 494

Applying quality characteristics to topic-based information 501

Chapter 13. Reviewing, testing, and evaluating technical information 515

Reviewing technical information 516

Testing information for usability 518

Testing technical information 524

Editing and evaluating technical information 527

Reading and editing the information 531

Reviewing the visual elements 536

Part 6. Appendixes 543

Appendix A. Quality checklist 545

Appendix B. Who checks which characteristics? 549

Glossary 555

Resources and references 565

Index 573




The authors are all long-standing and respected members of the information development community at IBM. Although the authors have served in various roles throughout their careers, information quality has always been and continues to be their primary focus.


Michelle Carey is an information architect and technical editor at IBM and has taught technical communication at University of California Santa Cruz Extension. Michelle is the co-author of the book DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA. She is an expert on topic-based information systems, software product error messages, grammar, embedded assistance for user interfaces, and writing for international audiences. She also writes computational linguistic rules for a grammar, style, and terminology management tool. Michelle enjoys teaching, grammar, herding cats, and riding and driving anything with a lot of horsepower.


Moira McFadden Lanyi is an information architect and technical editor at IBM. She has experience with topic-based writing, DITA, embedded assistance, user interface design, and visual design. She created 99% of the artwork in this book. She is a co-author of the book An Introduction to IMS. Moira enjoys visiting San Francisco with her family as often as possible, cooking fresh, healthy meals, and watching her courageous son ride his unicycle and surf.


Deirdre Longo is an information architect and strategist at IBM. She has been a pioneer for embedded assistance in IBM: defining the scope of that term, developing standards for embedded assistance, and modeling how to work effectively in cross-disciplinary teams. She has taught webinars for the Society of Technical Communication (STC) and published articles on information architecture topics in STC’s Intercom. She is an avid yoga practitioner.


Eric Radzinski is a technical editor and information architect for industry-leading mainframe database software at IBM. He is a co-author of The IBM Style Guide: Conventions for Writers and Editors and is well versed in topic-based writing, embedded assistance, DITA, and writing for a global audience. Eric makes his home in San Jose, California, with his wife and their three children.


Shannon Rouiller is an information architect and technical editor at IBM. She has experience with quality metrics, topic-based information systems, DITA, videos, embedded assistance, and user interface design. She is a co-author of the book Designing Effective Wizards. Shannon dabbles in sports photography and likes to solve puzzles.


Elizabeth Wilde is an information quality strategist at IBM, developing strategies and education for developing high-quality content. She develops Acrolinx computational linguistic rules that enforce grammar, style, and DITA tagging rules. She teaches an extension course in technical writing at the University of California Santa Cruz. Her hobbies include growing cacti and succulents and collecting tattoos.