Post on 14-May-2022
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