没有合适的资源?快使用搜索试试~ 我知道了~
Developing Quality Technical Information
需积分: 34 12 下载量 66 浏览量
2021-01-07
18:06:43
上传
评论 1
收藏 12.23MB PDF 举报
温馨提示
试读
457页
技术文档写作
资源详情
资源评论
资源推荐
Developing
Quality Technical Information
A Handbook for Writers and Editors
Document Number ISBN 013-790-320-0-02
Gretchen Hargis
Michelle Carey
Ann Kilty Hernandez
Polly Hughes
Deirdre Longo
Shannon Rouiller
Elizabeth Wilde
IBM is a registered trademark of International Business Machines Corporation. Lotus is a
registered trademark of IBM-Lotus Development Corporation. Java and all Java-based
trademarks are trademarks of Sun Microsystems, Inc. in the United States, other coun-
tries, or both. Microsoft and Windows are trademarks or registered trademarks of
Microsoft Corporation in the United States, other countries, or both.
Pqti.bk Page i Friday, May 30, 2003 7:20 PM
iii
Contents
Contents .....................................................................................................................iii
Welcome!....................................................................................................................xi
Is this book for you? ............................................................................................................................... xi
How to use this book............................................................................................................................ xii
Conventions used in this book............................................................................................................ xii
Changes in this edition......................................................................................................................... xiii
Acknowledgments.....................................................................................................xv
Chapter 1. Quality technical information ................................................................1
What is quality technical information? ................................................................................................ 3
Relationships among the quality characteristics................................................................. 4
Order of the groups ................................................................................................................. 4
Quality characteristics compared with elements and guidelines.................................... 5
Other possible quality characteristics of technical information ..................................... 6
Using the quality characteristics to develop quality technical information................................. 7
Preparing to write: understanding users, tasks, and the product .................................. 8
Writing and rewriting............................................................................................................... 9
Reviewing, testing, and evaluating technical information................................................ 10
Establishing a unit of reuse ....................................................................................................11
Restructuring technical information....................................................................................12
Pqti.bk Page iii Friday, May 30, 2003 7:20 PM
iv Developing Quality Technical Information
Part 1. Easy to use...........................................................................................................15
Chapter 2. Task orientation.....................................................................................17
Write for the intended audience........................................................................................................19
Present information from the user’s point of view......................................................................... 20
Indicate a practical reason for information ......................................................................................23
Relate details to a task where appropriate........................................................................23
Provide only a necessary amount of conceptual information in task topics..............24
Focus on real tasks, not product functions ......................................................................................27
Use headings that reveal the tasks .....................................................................................................31
Divide tasks into discrete subtasks .................................................................................................... 33
Provide clear, step-by-step instructions ............................................................................................ 36
Make each step a clear action for users to take...............................................................36
Group steps for usability .......................................................................................................38
Clearly identify optional steps ..............................................................................................41
Identify criteria at the beginning of conditional steps..................................................... 43
In sum........................................................................................................................................................45
Chapter 3. Accuracy .................................................................................................47
Write information only when you understand it, and then verify it .......................................... 49
Keep up with technical changes ..........................................................................................................53
Maintain consistency of all information about a subject................................................................58
Reuse information when possible........................................................................................60
Avoid introducing inconsistencies and eliminate those that you find.......................... 60
Use tools that automate checking for accuracy.............................................................................. 67
Check the accuracy of references to related information............................................................ 69
In sum........................................................................................................................................................72
Chapter 4. Completeness ........................................................................................75
Cover all topics that support users’ tasks, and only those topics .............................................. 77
Cover each topic in just as much detail as users need.................................................................. 79
Include enough information ..................................................................................................82
Include only necessary information..................................................................................... 84
Use patterns of information to ensure proper coverage..............................................................90
Repeat information only when users will benefit from it.............................................................. 96
In sum........................................................................................................................................................99
Pqti.bk Page iv Friday, May 30, 2003 7:20 PM
v
Part 2. Easy to understand ........................................................................101
Chapter 5. Clarity ...................................................................................................103
Focus on the meaning..........................................................................................................................105
Avoid ambiguity.....................................................................................................................................110
Use words with a clear meaning........................................................................................110
Avoid vague referents...........................................................................................................113
Place modifiers appropriately .............................................................................................114
Avoid long strings of nouns.................................................................................................116
Write positively .....................................................................................................................118
Make the syntax of sentences clear ..................................................................................120
Keep elements short............................................................................................................................124
Remove roundabout expressions and needless repetition..........................................124
Choose direct words............................................................................................................127
Keep lists short ......................................................................................................................129
Write cohesively...................................................................................................................................132
Present similar information in a similar way...................................................................................136
Use lists appropriately..........................................................................................................136
Segment information into tables........................................................................................139
Use technical terms only if they are necessary and appropriate...............................................141
Decide whether to use a term...........................................................................................141
Use terms consistently.........................................................................................................142
Define each term that is new to the intended audience.............................................................144
In sum......................................................................................................................................................146
Chapter 6. Concreteness .......................................................................................149
Choose examples that are appropriate for the audience and subject .....................................152
Consider the level and needs of users .............................................................................152
Use examples appropriately in conceptual, task, and reference information..........154
Use focused, realistic, accurate, up-to-date examples.................................................................160
Make examples easy to find ...............................................................................................................162
Use visual cues to indicate where examples are............................................................162
Make examples part of the user interface .......................................................................163
Make clear where examples start and stop.....................................................................163
Make code examples easy to adapt..................................................................................................166
Use scenarios to illustrate tasks and to provide overviews.......................................................169
Set the context for examples and scenarios..................................................................................172
Relate unfamiliar information to familiar information..................................................................174
Use general language appropriately..................................................................................................176
In sum......................................................................................................................................................178
Pqti.bk Page v Friday, May 30, 2003 7:20 PM
vi Developing Quality Technical Information
Chapter 7. Style ......................................................................................................181
Use correct grammar ..........................................................................................................................183
Check for sentence fragments ...........................................................................................184
Correct pronoun problems ................................................................................................185
Correct dangling modifiers..................................................................................................187
Use correct and consistent spelling .................................................................................................189
Use consistent and appropriate punctuation.................................................................................191
Write with the appropriate tone......................................................................................................193
Use an active style................................................................................................................................196
Use active voice .....................................................................................................................196
Use the present tense ..........................................................................................................198
Use the appropriate mood.................................................................................................................199
Follow template designs and use boilerplate text.........................................................................200
Create and reuse templates................................................................................................200
Use boilerplate text to ensure inclusion of necessary information...........................201
Create and follow style guidelines....................................................................................................203
Provide practical and consistent highlighting...................................................................205
Present list items consistently ............................................................................................207
Use unbiased language..........................................................................................................208
In sum......................................................................................................................................................211
Part 3. Easy to find .....................................................................................213
Chapter 8. Organization ........................................................................................215
Organize information into discrete topics by type.......................................................................218
Organize tasks by order of use.........................................................................................................222
Organize topics for quick retrieval...................................................................................................225
Separate contextual information from other types of information..........................................228
Organize information consistently ...................................................................................................232
Provide an appropriate number of subentries for each branch.................................................234
Emphasize main points; subordinate secondary points ...............................................................236
Reveal how the pieces fit together...................................................................................................239
In sum......................................................................................................................................................243
Chapter 9. Retrievability ........................................................................................245
Facilitate navigation and search .........................................................................................................247
Provide a complete and consistent index .......................................................................................249
Use an appropriate level of detail in the table of contents.........................................................254
Provide helpful entry points...............................................................................................................257
Link appropriately.................................................................................................................................260
Design helpful links ..............................................................................................................................264
Ensure that a link describes the information that it links to .......................................264
Pqti.bk Page vi Friday, May 30, 2003 7:20 PM
剩余456页未读,继续阅读
jcx66ds
- 粉丝: 0
- 资源: 1
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功
评论0