Writing Better Computer User Documentation From Paper to Hypertext Version 2.0

R. John Brockmann Associate Professor Concentration in Business and Technical Writing Department of English University of Delaware Newark, Delaware

John Wiley & Sons, Inc. New York / Chichester / Brisbane / Toronto / Singapore

/

CONTENTS

INTRODUCTION

Colophon iv List of Illustrations and Tables xiii Acknowledgements xvii

What's the Purpose of this Book? 1 Focus on End-User Not Design or Maintenance

Documentation 1 Focus on Problems Deeper than Grammar,

Spelling, or Punctuation 3 Focus on a Standard Methodology 4

Who Are the Intended Audiences? 5 What is Covered, and How is it Organized 6 Why a Revised Edition? 6 What Principles Guide this Book? 8 What's the Best Way to Read this Book? 10

PART ONE: T H E DOCUMENTATION PROBLEM

Overview of Computer Documentation 12 Purposes of Software User Documentation 1 2 Liability Issues in Documentation 1 3 Types of User Documentation 14 What Choice Is There in Where to Put

"System Intelligibility?" 17 Why Is Inadequate User Documentation

Produced? 21 Beyond Computer System Centralization 2 2 Institutional Limitations 2 2 Inadequate Design:

The CASE Tool Solution 2 6 Techniques Used in User Documentation 2 8 Oversimplifying the Writing Task 2 9 Fighting Rather than Harnessing

Learning Behaviors Adults Spontaneously Adopt 3 1

Natural Egoism 3 2 Example of Inadequate Paper Manual 3 3

Problems with the Example User Manual 4 6 What Surveys Find Concerning Paper

Documentation 4 9 AT&T 1986 External Documentation

Market Survey 5 0

viii CONTENTS

Microsoft Corporation Documentation Survey 5 0

PC User Group Survey 5 1 Why On-line Documentation? 5 2

Why Should Paper Manual Writers Care About On-line Documentation? 5 4

On-line Documentation Is Like Paper...But 5 6

Example of Inadequate On-line Documentation 61

What Are On-line Documentation's Unique Problems? 6 7 Physical Differences Between Paper

and On-line Documentation 6 5 Organizational Differences Between

Paper and On-line Documentation 69 Rhetorical Differences Between Paper

and On-line Documentation 7 0 What Surveys Find Concerning 7 2

On-line Documentation 1986 Control Data Survey 72 1986 Survey of Super Computer Users

of the DOCUMENT System 7 5 The Solution: The Standard

Documentation Process 7 7

PART T W O : T H E STANDARD DOCUMENTATION PROCESS

STEP 1: DEVELOPING THE DOCUMENT SPECIFICATIONS

What Are Document Specifications? 84 How Do You Know When Your

Specification is Complete? 86 Why Develop Specifications? 86 How Long Does It Take to Develop

Specifications? 89 How Do I Develop a Library or Individual

Document Specification? 89 Break Down Documentation By Tasks 90 Use a Minimalist Design Philosophy 9 3 Minimalist Design Cases 95

CONTENTS ix

Problems with Minimalist Design 100 Plan for an Audience 101

Relative Computer Sophistication 102 An Audience's Background, Training, and

Education 106 An Audience's Attitude Toward the

Message and Change 107 Multicultural Documentation 109 How to Deal With Diverse Audiences 116

State the Purpose for Each Document 118 Organize Information 119 Techniques to Overcome On-line

Organizational Problems 122 Chunking Information 122 Creating The On-line Navigational

Buoys 123 Moving Through On-line Information:

Hypertext and Keyword Search 125 Use Windows or Split Screens 129 Future Ways of Organizing On-line

Documentation: Hypertext Intelligent Assistants 129

Develop a Product Visualization 130 Using Visualizations to Overcome On-line

Rhetorical Problems 131 Pick the Appropriate Medium 133

Paper Media Example: Quick Reference Cards 135

On-line Documentation Example: Optical Discs 137

Decide on Typography, Layout, Color and Page Size 139 Typographic Considerations 139 Layout 153 Color—Use for Coding,

Not Comprehension 157 Page Sizes 162

Techniques to Overcome On-line Physical Problems 163 Getting Some Ideas From Effective

Paper Design 163 Unique On-line Typography and Design

Techniques 167 Plan for Updating 168 Consider the Competition 169

X CONTENTS

STEP 2: PROTOTYPING THE DOCUMENT

What Is Prototyping? 177 How Do You Go About Prototyping a

Document? 180 One Company's Approach to Prototype

Testing 182

STEP 3: DRAFTING THE DOCUMENT

Overcome Writer's Block 186 Internal Writing Block 187 External Writing Blocks from

Information Sources 188 External Writing Blocks in Team Writing 189

Use an Appropriate Writing Style 191 How Do Readers Read Documentation? 191 Reader-Engineered Writing Styles 192 FOMM (Functionally Oriented

Maintenance Manuals) 193 STOP (Sequential Thematic

Organization of Proposals) 196 Playscript 199 Structured Writing 203

Employ Reader-Based Writing Techniques 212 Using Examples and Metaphors 212 Providing Interrelated Examples

Called Cases 213 Using a Conversational Style 214 Avoiding the Use of Humor 214 Using the Scenario-Writing Principle 216

Develop Effective Graphics 217 Principles Behind Effective Graphics 221

Create Your Reference Aids 2 2 5 Glossary 226 Indexes 22 7 Headings 2 32

Consider Your Packaging 2 33

CONTENTS xi

STEP 4: EDITING THE DOCUMENT

General Editing Principles 237 Specific Editing Principles

Levels Of Edit 2 39 Language Edit 241

Edit Contextually 241 Maintain Coherence 243 Weed Out Abstractions 244 Minimize Sentence Complexity 24 5 Eliminate Nonessential Preliminaries 246 Break Up Dense Writing 24 7 Watch Out for Jargon, Abbreviations,

and Acronyms 248 Rules of Editing Best Forgotten 251

STEP 5: REVIEWING THE DOCUMENT

Choose Reviewers and the Time to Review 2 54 Review Copy-Circulating Strategies 255

Show Reviewers How to Review 2 56 Give Feedback to Reviewers 259

STEP 6: FIELD-TESTING THE DOCUMENT

Choose Field Testers and the Time to Field Test 262

Run the Field Test 2 62 Give Feedback to Field Testers 263

STEP 7: PUBLISHING THE DOCUMENT

The Old-Fashioned Way 265 The Way of the Future: SGML 266 The Dangers of SGML-like Techniques 2 70

STEP 8: POST PROJECT REVIEWING

What Is a Post Project Review and Why Have One? 275

xii CONTENTS

STEP 9: MAINTAINING THE DOCUMENT Maintaining The Document 2 77

BIBLIOGRAPHY

"Bibliography 281

GLOSSARY

Glossary 315

INDEX

"index 3~2T

About the Author 365

QUICK REFERENCE TEAR O U T CARD