Upload
ngokhanh
View
226
Download
0
Embed Size (px)
Citation preview
301Index
INDEX
Symbols:), 254
Aabbreviations, punctuation in, 287above (word usage), 69abstracts, 187
definition of, 291in lab reports, 216research proposals, 191
Acrobat Distiller, 177Acrobat Reader, 176, 177acronyms, 33
consistency, 33expanding, 33for nonnative speakers, 14punctuation in, 287
active voice, 46definition of, 291lab reports, 47strengths, 47
ADHD example, 216adjectives, 36
in business proposals, 203administration manuals
screenshots, 93Adobe, 177advanced topics, 138adverbs, 36
in business proposals, 203affect (word usage), 42air pressure example, 114algebraic formulas, explanations of, 112
aligninggraphics, 108text in graphics, 97
alternate explanations, 120anecdotes in footnotes, 123Arial font, 273
Web sites, 167arrows, 97
as pointers, 104focus, 106
articles in magazines, 196assembly in high-level technical specs, 209attention span
of Web site visitors, 166PowerPoint presentations, 234, 243winning it, 5
audience, 9agitated, 17appropriateness, 4becoming, 19book proposals, 195, 196, 197breadth, 12business plans, 198college freshmen, 112defining in a home page, 164defining in a preface, 150definition of, 291doc spec example, 23documentation project plans, 25educational level, 10emotional state, 17empathy for, 19engaging, 190, 227examples, 114experience, 11
TechnicalWriting.book Page 301 Wednesday, April 20, 2005 2:34 PM
302 Index
audience (contd.)expertise, 11for this book, 20formula-based rules, 112gaining empathy for, 19getting attention of, 5giving directions, 68glossaries, 151high-level technical specs, 206market research data, 9medium and message, 18motivation of, 17older, 278peers, 238question-and-answer format, 118research proposals, 190summary of, 20superiors, 238tone in Web sites, 167visualization, 9Web site, 162
auditory learners, 242
Bback matter, 24background colors
in PowerPoint presentations, 235in Web sites, 105
background informationin business proposals, 204in tutorials, 136
bar chartsin business proposals, 205PowerPoint presentations, 239
baseball terms and native culture, 15becoming the audience, 19before-and-after graphics, 89beginner’s mind and tutorials, 136below (word usage), 69BentonGothic font, 273beta tests
documentation, 268online help, 144
biographies, 185examples, 186research proposals, 191
block diagrams, 97definition of, 291white space example, 107
body language, 245bold, 279
in graphics, 97Book of Lists, The, 63book proposals, 181, 195
audience, 196contents, 196example marketing section, 197preproposals, 182strategy, 195
breadth of audience, 12breathing to relax, 246brevity
online help, 143secondary pages, 174
British readers, 15browsers, default fonts, 167budgets in research proposals, 191bugs
in release notes, 147, 148tracking, 266
bullet symbols, 64bulleted lists, 64
capital letters in, 71definition of, 291elements in, 65in cookbook-style manuals, 134introducing, 69length of elements, 66number of elements in, 64online help, 144parallel, 70periods in, 71PowerPoint presentations, 236second-level, 236vs. embedded lists, 50vs. numbered lists, 63
business plans, 181, 198audience, 198bios of consultants, 186contents, 199definition of, 291marketing, 199vs. business proposals, 202
TechnicalWriting.book Page 302 Wednesday, April 20, 2005 2:34 PM
303Index
business proposals, 201, 202analysis, 203definition of, 291example, 204, 205marketing, 203summary, 213vs. business plans, 202
by comparison (transition), 56by contrast (transition), 56
Ccallouts, 90
definition of, 292font height, 277fonts, 275
can (word usage), 41capital letters in list elements, 71captions
alignment of graphics, 108definition of, 292editing, 263, 269tables, 83
cascading style sheets (see CSS)cells
amount of text, 80units of measure, 75
centeringgraphics, 108
Chicago Manual of Style, 283Chinese language, 13Chinese restaurants metaphor, 49choppy sentences, 51chunks, 138
definition of, 292citations in lab reports, 225clarity, 4
in business plans, 198in editorial comments, 261, 269in internal planning documents, 201in research proposals, 190in speaking, 243
cliches, 40click here hyperlinks, 172client-server architecture example, 115clip art in PowerPoint presentations, 239clutter in layout, 107colons, 288
colorblock diagrams, 97contrasting, 94discontinuities, 105hyperlinks, 173PowerPoint presentations, 235Web sites, 167
color blindness, 95, 96definition of, 292
column headersin tables, 74
commands (see imperative verbs)commas, 284
parenthetical clauses, 52that vs. which, 41
comparing technical writing to engineering,8
components listhigh-level technical specs, 207low-level technical specs, 211
conceptual entries in indexes, 158concise
example of, 5FAQs, 179phrases, 40secondary pages, 174sentences, 49writing, 4
conclusions, 6lab reports, 224PowerPoint presentations, 228
conjunctionsdefinition of, 292semicolons, 286starting a sentence with, 57vs. transitions, 57
consistencyfooters, 263graphics, 97, 98headers, 263labels, 127of terminology, 99of word usage, 33reference pages, 140
content management software, 163context-sensitive help, 143
definition of, 292contingency plans, 188contrast in color or shading, 105
TechnicalWriting.book Page 303 Wednesday, April 20, 2005 2:34 PM
304 Index
cookbook style manuals, 134definition of, 292example of, 135
copyediting, summary of, 269copy editors, 259, 263
definition of, 292cover letters, 184
definition of, 292research proposals, 191
criticism, 241, 269e-mail messages, 255
cross-cultural examples, 16cross-references, 140CSS (cascading style sheet), 278
definition of, 292cultural differences, 15, 16
e-mail, 252cummings, e.e., 253
DDanish language, 13dashes, 285
parenthetical clauses, 52data analysis in research proposals, 194dates, in different countries, 16defects in documentation, 266definitions in glossaries, 151descriptions
examples in, 114of geometric figures, 127precise, 126
design of research proposals, 194design specs, 210
definition of, 292developmental editors, 259
definition of, 292diabetics example, 165diagnostic information, 140dialog in question-and-answer format, 118dictionary-style documentation, 140digital photography, 100
enhancing with line art, 101establishing shot, 102
digressions, 124footnotes, 123online help, 144
sidebars, 122within a sentence, 52
directions, giving, 68discontinuities, 105Discussion section of lab reports, 223doc project plans
definition of, 292example of, 26how to write, 25summary of, 28
doc specsdefinition of, 293example, 23how to write, 22issues list, 24outline example, 24purpose of, 21reviewers list, 24summary of, 28
documentationbeta tests, 268conflicts, 267cost of screenshots, 94for programmers, 116guides, 138, 139pace, 122question-and-answer format, 118reference manuals, 140schedules, 267sets, 25structured, 138
documentation planning, 21–28documentation project plans (see doc project
plans)documentation specifications (see doc specs)documents
legal, 60optimum number, 25
drop-dead-date in cover letters, 184dull writing, 5dynamic content, 163
definition of, 293
Eediting, 259–269
a superior’s work, 262
TechnicalWriting.book Page 304 Wednesday, April 20, 2005 2:34 PM
305Index
copy editor, 263diplomacy, 262distributing, 263effective, 260e-mail messages, 252hardcopy, 265online, 265relationship with writer, 260–262schedules, 267summary, 269time allocated, 267tracking bugs, 266your own document, 264
educational level of audience, 10effect (word usage), 42elements
definition of, 293in bulleted lists, 65in numbered lists, 67length of, 66parallel, 70periods, 71
elevator speeches, 182definition of, 293
em dashes, 285e-mail messages, 249–256
cowardice, 254debates in, 267editing, 252miscommunications, 255Pickford Paradox, 249problems with, 250summary, 256vs. formal documents, 251vs. telephone conversations, 254wars, 147
embedded labels, 91definition of, 293
embedded lists, 50, 64commas in, 284
emergencies, in index, 17emoticons, 254emotional state
e-mail messages, 256of audience, 17
empathy with readers, 19, 138encyclopedic documentation, 140en-dashes, 285
endnotes, 123definition of, 293
engaging audiences, 4, 5pace, 122PowerPoint presentations, 227, 234,
243engineering
audience analysis of product, 144compared with technical writing, 8context-sensitive help systems, 143documentation process, 266editing process, 264management, 202, 238plans for teams, 212role of documentation plans, 21specs, 209
engineersbiographies, 186business proposals, 202commenting code, 140editing, 259e-mail messages, 251in management, 32jargon, 32low-level technical specs, 210planning documents, 201presenting revolutionary ideas, 189proposals, 181resistance to marketing, 36specs, 201success and failure, 7wardrobe, 245
English as a pervasive technical language, 13English as a second language, 13, 47
e-mail messages, 256equipment in lab reports, 219Ernest Hemingway, and readability, 50error codes, 17
in reference pages, 140establishing shot, 102, 103European readers and English, 13examples, 114
abstract in lab reports, 216abstract in proposals, 187active voice, 46air pressure, 114beyond the obvious, 125biographies, 186
TechnicalWriting.book Page 305 Wednesday, April 20, 2005 2:34 PM
306 Index
examples (contd.)bones in little finger, 90book proposals, 197business proposals, 204client-server architecture, 115color to grayscale, 125Conclusion section of lab reports, 224contingency plans, 188cookbook-style manuals, 135cover letter, 184design and methods of research propos-
als, 194digestive system, 91digital photography, 101Discussion section of lab reports, 223doc specs, 23documentation project plans, 26DOS and UNIX commands, 78electron microscope, 150elevator speeches, 182e-mail messages, 250, 252engaging, 5Experimental Procedure in lab reports,
220firewall, 119for color blindness, 96for this book, 20gas pressure, 114glossary, 152graphics in PowerPoint, 239gravitational force, 112, 113guides, 139Hello World, 116high-level technical specs, 208hot air and cold air, 5hurricanes, 194hyperlinks in body text, 172introduction in lab reports, 218it and they, 39jargon and audience, 11juggling, 101, 102length of, 138low-level technical specs, 211Materials section of lab report, 219metaphors, 115navigators in Web sites, 170online help, 145, 146passive voice, 48PowerPoint lists, 236
PowerPoint presentations, 233precision descriptions, 127preface, 150programming documentation, 116question-and-answer format, 119reference pages, 141release notes, 148research proposal objectives, 193Results section in lab reports, 222revolutionary proposals, 189sans-serif fonts, 273serif fonts, 273significance statements, 192table of contents, 153, 154title of Web sites, 165to explain rules, 112tutorials, 137white space, 108you, 38
exceptions to rules, 112example of, 113
exclamation points, 287Experimental Procedure section in lab re-
ports, 220explanations, 112
alternate, 120precise, 126
eyes as pointers, 104, 106
Fface mask example, 142failure
in cookbook style manuals, 134in proposals, 188
familiarity of topic, 11FAQs, 178
definition of, 293vs. question-and-answer format, 118
fear of speaking, 246feedback on documentation, 268fiction
audience motivation, 17conjunctions, 57Henry James, 52linear access, 18metaphors, 115reputation of author, 196
TechnicalWriting.book Page 306 Wednesday, April 20, 2005 2:34 PM
307Index
vs. technical writing, 3word usage, 10
figures(see also graphics)colons, 288editing, 263
final doc specs, 22firewall example, 119fixed-width fonts, 274fluffy phrases, 40focus, 104
discontinuities, 105on page, 106
following (word usage), 69fonts, 271–282
callouts, 277captions, 277Courier New, 274default, 273definition of, 293example of online help, 146fixed-width, 274foreign phrases, 279hard copy documents, 275headers, 277height of, 277in graphics, 97in HTML, 176in PDF, 176italics, 279lists, 277Lucida Console, 274paragraphs, 277points, 277PostScript, 281PowerPoint presentations, 235sans-serif (see sans-serif fonts)screen resolution, 278serif (see serif fonts)size, 277summary, 282tables, 277titles, 279True-Type vs. PostScript, 281Type 1, 281variable width, 274Web pages, 278Web sites, 167weight of, 272, 273
footersediting, 263fonts, 275
footnotes, 123definition of, 293online help, 144
for example (transition), 56foreign phrases, fonts, 279formulas
explaining, 112of technical writing, 8readability, 50
frequently asked questions (see FAQs)Freud, Sigmund, and footnotes, 123front matter, 24function names, 116functional specs (see high-level technical specs)
GGaramond font, 273general online help systems, 143generic verbs, 34geometric descriptions, 127glossaries, 151
example of, 152jargon, 32
Goldberg, Isaac, quote, 4golden rule of indexing, 155grammar
and native language, 13politically correct, 37
grammatically parallel (see parallelism)grand finale, 244graphics, 85–109
alignment on page, 108before and after, 89block diagrams, 97clutter, 88, 107consistency, 98digital photography, 100establishing shot, 102FAQs, 179geometric descriptions, 126gray, 96home page, 166in lab reports, 220introducing, 99
TechnicalWriting.book Page 307 Wednesday, April 20, 2005 2:34 PM
308 Index
graphics (contd.)labels, 90, 91, 99layout, 104online, 88orienting readers, 92photography and line art, 101pointers, 104PowerPoint presentations, 239, 240summary, 109telling a story, 142three-dimensional, 98white space, 107
graphsdetail in, 88time-series, 86, 87
gravitational force example, 112, 113grayscale, 96guides, 138
definition of, 294
Hhappen (word usage), 34hard-copy documents
fonts, 275, 276PowerPoint presentations, 240vs. Web sites, 161
he (word usage), 37headers
definition of, 294editing, 263fonts, 275, 277in tables, 74numbering, 60table of contents, 153, 154
height of Web pages, 174Hello World examples, 116
definition, 294help systems (see online help)helping the reader, 4Hemingway, Ernest, and readability, 50hierarchies
bulleted lists, 65headers, 60
high-level technical specs, 201, 206analysis, 207definition of, 294example, 208
summary, 213highlighting in screenshots, 94home pages, 164
audience definition, 164definition of, 294engaging, 166stating purpose of, 164summary, 180tone, 167
honestybiographies, 185hyperlinks, 172lab reports, 221
horizontal scrolling, 174HTML
<TITLE>, 164definition of, 294online help, 143relationship to SGML, 280sample of a guide, 139vs. PDF, 176, 177
humorin FAQs, 179in PowerPoint presentations, 230in prefaces, 149
hurricane examples, 194glossary, 152research proposals, 193
hyperlinks, 18color, 173glossaries, 151in body text of Web sites, 172in FAQs, 179in navigators, 170in online help, 144in reference pages, 140right number of, 173target windows, 173
hypotheses, 193Discussion section of lab reports, 223in lab reports, 216in research proposals, 193
Iideas per sentence, 51ideas, revolutionary, 189illustrations (see graphics)
TechnicalWriting.book Page 308 Wednesday, April 20, 2005 2:34 PM
309Index
imperative verbs, 67definition of, 294
in other words (transition), 56, 120indexing, 155
conceptual entries, 158editing, 269entries for emergencies, 17examples, 156length, 155permuting terms, 157precise entries, 156
information density, 122Web pages, 167
ingredients in cookbook-style manuals, 134inoculation, 11, 189
business proposals, 203installation manual screenshots, 93internal planning documents, 201–213Internet, 161
distributing documents on, 176random access, 161search boxes, 171
introduction ofdocument, 6graphics, 99, 288lab reports, 217, 218lists, 60, 69, 288new terms, 33, 118paragraphs, 55, 58PowerPoint presentations, 228proposals, 184research proposals, 194tables, 288topics, 136Web sites, 175yourself, 182
it’s (word usage), 42italics, 279
in graphics, 97its (word usage), 42
JJapanese culture
baseball, 15personal checking accounts, 16
jargon, 32audience experience, 11
definition of, 294e-mail messages, 256Web sites, 167
javadoc, 140jokes
in footnotes, 123in PowerPoint presentations, 230
juggling examples, 101, 102, 103
KKernighan and Ritchie, 116key principles of technical writing, 4King Kong social climber
business proposal, 204high-level technical spec, 208low-level technical spec, 211
Llab reports, 215–226
abstracts, 216citations, 225Conclusion section, 224Discussion section, 223equipment list, 219Experimental Procedure section, 220introduction, 217Materials section, 219passive voice, 47References section, 225Results section, 221, 222sections in, 215summaries of, 226tense, 35
labels in graphics, 90, 91, 99consistency, 127
language, native, 13lay audience
explaining rules, 112tables, 73using jargon, 32Web sites, 167
layout, 104definition of, 294eyes on page, 106Web pages, 168
learning styles, 242
TechnicalWriting.book Page 309 Wednesday, April 20, 2005 2:34 PM
310 Index
legal documents, 18, 60length
of books, 23of documents, 25of elements in numbered lists, 67of paragraphs, 58of PowerPoint presentations, 228of sentences, 49
levels of sections, 60line art, 101lists, 63–72
bulleted, 64citations, 225colons to introduce, 288commas in, 284directions, 68embedded, 50fonts, 275introducing, 69length of elements, 66numbered, 67of equipment in lab reports, 219parallel, 70periods in, 71PowerPoint presentations, 236section headers, 60summaries of, 72to break up blocks of text, 122types of, 63
literary editing, 269literary editors, 259long sentences, 49
causes of, 50reducing, 51
low-level technical specs, 201, 210definition of, 295example, 211summary, 213
lying in a biography, 185
MMacintosh fonts, 281magazine articles, 196males and color blindness, 95managers
learning styles, 242motivation, 202
manuals, 133–159definition of, 295guides, 138in documentation project plans, 26indexes of, 155motivation to read, 17nonverbal, 142reference, 140structured documentation, 138summary of, 159tutorial example, 137tutorials, 136vs. online help, 143
mapsgray, 96in tourist areas, 92
marketdefining in proposal, 187
marketingengineers’ dislike of, 36in book proposals, 197in business plans, 198, 199in business proposals, 203, 204in high-level technical specs, 207in PowerPoint presentations, 232
materials in lab reports, 219may (word usage), 41McNealy, Scott, and PowerPoint, 227media
in documentation project plans, 27plan, 25
medium and the message, 18men and color blindness, 95menus, documenting, 145metaphors, 115
native culture, 15methods in research proposals, 194microscopy example, 150miscommunications in e-mail, 255misunderstandings and language, 13monospaced fonts, 274mood of audience, 121motivation of audience, 17movies as cross-cultural examples, 16multimedia, 175musical punctuation, 283mysteries
PowerPoint presentations, 233Web sites, 166
TechnicalWriting.book Page 310 Wednesday, April 20, 2005 2:34 PM
311Index
NNational Science Foundation, 181, 191native culture, 15
dates, 16examples, 16for this book, 20
native language, 13e-mail messages, 256for this book, 20simple words, 14
navigators in Web sites, 170two-level, 171
nevertheless (transition), 56newspaper layout, 168non-goals in doc specs, 23non-native speakers, 13nonparallel (see parallelism)nonverbal manuals, 142
definition of, 295nouns versus adjectives, 36NSF, 191numbered lists, 67
capital letters in, 71definition of, 295directions, 68in citations, 225in cookbook style manuals, 134introducing, 69online help, 144parallel, 70periods, 71vs. bulleted lists, 63vs. embedded lists, 50
numbering section headers, 60
Oobjectives in research proposals, 193occur (word usage), 34okay (word usage), 15online editing, 265online help, 143
best practices, 144categories, 143definition of, 295examples, 145, 146
opening chapter of a book, 6
ordinal numbers in directions, 68organizing writing, 6outline in doc specs, 24
Ppace, 122
definition of, 295of speaking, 243PowerPoint presentations, 234
page counts, 25page layout, 106page templates, 168, 169
definition of, 295page-oriented documentation, 138pages in a Web site (see Web pages)Palatino-Linotype font, 273panic attacks while speaking, 246paper
advantages and disadvantages, 18editing on, 265pros and cons, 18vs. Web sites, 161
paragraphsfonts, 275informational content of graphics, 240length of, 58one-sentence, 58opening sentence of, 6pace, 122summary of, 61transitions, 59
parallelismdefinition of, 295in tables, 79in tables of contents, 154section names, 60
parentheses, 287parenthetical clauses, 52
definition of, 295parsimony in writing, 8parts, 33
labelling in graphics, 90naming, 127
passive voice, 46acceptable uses, 48definition of, 295e-mail messages, 252
TechnicalWriting.book Page 311 Wednesday, April 20, 2005 2:34 PM
312 Index
passive voice (contd.)lab reports, 47lengthy sentences, 50weaknesses, 47
past tense, 35pauses, 283PC fonts, 281PDF
definition of, 296in documentation project plan, 27vs. HTML, 176, 177
periods, 287in list elements, 71
permuting index entries, 157photographs
and line art, 101establishing shot, 102offending, 16telling a story, 142Web sites, 167
picas, 296Pickford Paradox, 249pictures (see graphics)pie charts in business proposals, 205planning, 201–213
documentation projects, 21–28for failure, 188media, 25Web sites, 162
pointers, 104definition of, 296eyes, 106
points, 277definition of, 296
politically correct grammar, 37pop-up graphic detail, 88positive reinforcement, 261, 269PostScript fonts, 281PowerPoint, 296PowerPoint presentations, 227–247
attention span, 243background images, 235body language, 245body slides, 234color, 235fear of speaking, 246final slide, 241fonts, 235grand finale, 244
graphics, 239, 240interruptions, 229introductions, 233learning styles, 242lists, 236marketing speak, 232mystery style, 233number of slides, 229opening slides, 231organizing, 228pace, 234pre-show, 244printing, 240question-and-answer sessions, 241relaxation techniques, 246speaking, 243, 245speech, 244starting, 229, 230summary of, 247to superiors, 238what to wear, 245
preceding (word usage), 69prefaces, 149
example, 150preliminary doc specs, 22preproposals, 182present tense, 35pre-show, 244primary keys vs. table columns, 77Princess Bride, The, 123principles of technical writing, 4principles, explaining, 112printing
HTML vs. PDF, 176PowerPoint presentations, 240
professional secrets, 111–129summary of, 129
programming documentation, 116, 117quotes, 290
project description in proposals, 191project plans, 25
(see also documentation project planspronouns, 37, 38, 39proposal review committees, 190proposals, 181–200
abstracts, 187biographies, 185books, 195business, 202 (see also business proposals)
TechnicalWriting.book Page 312 Wednesday, April 20, 2005 2:34 PM
313Index
business plans, 198commonalities, 181contingency plans, 188convincing reviewers, 189cover letters, 184definition of, 296elevator speeches, 182importance of, 181inoculating against skepticism, 189preproposals, 182research (see research proposals)revolutionary ideas, 189summary, 200templates, 183within your company, 202
public speaking, 241, 243crippling fear of, 246
publishers, 195punctuation, 283–290
colons, 288commas, 284dashes, 285emoticons, 254hyphens, 285periods, 287quotation marks, 289semicolons, 286
QQA (see quality assurance)Q-and-A format (see Question-and-Answer
format)quality assurance
beta-tests, 268documentation, 267
Question-and-Answer format, 118definition of, 296example of, 119
Question-and-Answer sessions, 241PowerPoint presentations, 228
questions in FAQs, 178quotation marks, 289
RR2D2 as a cross-cultural example, 16
random access of information, 18readability quotients, 50
definition of, 296readers (see audience)reference manuals, 140
definition of, 296example, 141motivation to read, 17
References section of lab reports, 225release notes, 147
definition of, 296example of, 148in documentation project plans, 26
repetition, 6, 50reports, status, 253research proposals, 181, 190, 193
audience, 190contents of, 191contingency plans, 188data analysis, 194design and methods, 194methods, 194methods and materials, 194objectives, 193overview of experiment, 194significance statements, 192strategy, 190
Research section of lab reports, 224resolution of different media, 18results in research proposals, 194Results section in lab reports, 221reviewing documents, 259rhetorical questions, 114romantic-comedy style of overviews, 231rows of a table, sorting, 78rules in tables, 81
alternative, 82definition of, 296
rules, explanations of, 112run-on sentences, 45, 51
definition of, 297
Ssafety equipment, 142safety issues and tone, 121sans-serif fonts, 272
definition of, 297
TechnicalWriting.book Page 313 Wednesday, April 20, 2005 2:34 PM
314 Index
sans-serif fonts (contd.)examples of, 273hard-copy documents, 275height of, 277soft-copy documents, 276Web sites, 167
schedulesdoc specs, 22documentation project plans, 25in documentation projects, 267in high-level technical specs, 209
schematics, in documentation project plan,27
science, compared with technical writing, 8scientific writing
creativity, 5value of, 3
scientistsaiming documents at, 36editing, 259fashion sense, 245Q-and-A format, 118research proposals, 190revolutionary proposals, 189technical reviews, 259writing and, 8writing lab reports, 215
screen resolution and fonts, 278screenshots, 93
cost of, 94definition of, 297highlighting, 94
scrollingHTML vs. PDF, 176
search boxes in Web sites, 171search engines, 162secondary pages, 162
definition of, 297summary, 180
second-level index entries, 157sections, 55, 60, 153
numbering headers, 60summary of, 61
self-doubt, xx, 128self-editing, 128semicolons, 286sentence fragments in bulleted lists, 65sentence variety, 35
passive voice, 48
sentences, 45–53active voice, 46choppy, 51deleting unnecessary, 53digressions, 52long, 50number of words in, 50opening a section, 60opening in a paragraph, 6passive voice, 46per paragraph, 58repetition, 50run-on, 45, 51semicolons, 286short vs. long, 49starting with conjunction, 57strong, 47summary of, 53topic, 55transitions, 56variety of, 48
serif fonts, 272definition of, 297examples of, 273hard-copy documents, 275height of, 277soft-copy documents, 276
serifs, 272SGML, 280
definition of, 297shading
discontinuities, 105in tables, 82
she (word usage), 37short sentences, 49sidebars, 122signal-to-noise ratio
fonts, 275, 276readability, 50sentences, 45
significance statements, 192definition of, 297
silent films, 249size of fonts, 277skeptical readers, 11slang
e-mail messages, 256native culture, 15
slides (see PowerPoint presentations)
TechnicalWriting.book Page 314 Wednesday, April 20, 2005 2:34 PM
315Index
smiley faces, 254soccer in examples, 15soft-copy documents
editing, 265fonts, 276, 278
software documentationquotation marks, 290release notes, 148
software manualscookbook example, 135example of a guide, 139guide example, 139nonverbal treatment, 142tutorial example, 137
sorting rows in a table, 78speaking, 243
fear of, 246specifications (see specs)specs, 201–213
design, 210functional, 206high-level technical, 206low-level technical, 210
speech, 243lessons from professional entertainers,
244overcoming fear, 246telling jokes, 230transitions, 57
spell checkers, 263, 264, 266context problems, 269
split infinitives, 13Spring Into Series, 138stage freight, 241Standard General Markup Language, 280stapler and ruler example, 113starting a project, 128static content in a Web site, 163
definition of, 297stet, 297straight quotes, 290strong verbs, 34structured documentation, 138
relation to reference manuals, 140subheads within Web pages, 175subjects
active vs. passive, 46missing, 47obscuring, 48
sublists, 65sugar, spoonful of, 261summaries
business proposals, 213doc specs, 28documentation project plans, 28editing, 269e-mail messages, 256fonts, 282graphics, 109high-level technical specs, 213home pages, 180lab reports, 226lists, 72low-level technical specs, 213manuals, 159paragraphs, 61PowerPoint presentations, 247professional secrets, 129proposals, 200secondary pages, 180sections, 61sentences, 53tables, 84Web sites, 180words, 43
summarizing in technical writing, 6Sun Microsystems, 227support organizations and release notes, 147Swedish language, 13synopsis
business proposals, 204high-level technical specs, 207, 208low-level technical spec, 211
Ttables, 73–84
amount of text in cells, 80audience reaction, 73captions, 83colons, 288column headers, 74editing, 263font height, 277fonts, 275for variety, 122introducing, 76
TechnicalWriting.book Page 315 Wednesday, April 20, 2005 2:34 PM
316 Index
tables (contd.)leftmost columns, 77organizing, 77parallel, 79referring to, 76rules in, 81shading, 82sorting, 78summary of, 84titles, 83vs. primary keys, 77
table of contents, 153editing, 263, 269entries for emergencies, 17example, 154
technical editing, 259(see also editing)summary of, 269
technical editors, 259technical overview in high-level business
specs, 207technical writing
compared with engineering, 8creativity, 5formulas, 8overview, 3–8practicing, 4success and failure, 7theorems, 4topic sentences, 55value of, 3vs. fiction, 3vs. painting, 4
technology overview in technical specs, 208television
affect on reading, 161vs. Web sites, 166
Tell ’em, 6temperature graphs, 86, 87, 88templates
proposals, 183Web pages, 168Web sites, 169
tense, 35terminology
consistent, 99testing
documentation, 268jokes, 230
online help, 144technical writing and engineering, 8
that (word usage), 41that is (transition), 56, 120then (word usage), 67theorems of technical writing, 4there is (word usage), 34, 35they (word usage), 37thoughts per sentence, 51three-dimensional graphics, 98time allocation in PowerPoint presentations,
228, 229time of day for presentations, 234time-series graphs, 86, 87
definition of, 297tire example, 114titles
of PowerPoint slides, 231of tables, 83of Web pages, 164
to be (word usage), 34TOC (see table of contents)tone, 121
definition of, 298FAQs, 179Web sites, 167
topic sentences, 55tourist maps, 92tracking documentation bugs, 266trademarks, 263transistors, 32transitions, 56, 57
between paragraphs, 59definition of, 298semicolons, 286vs. conjunctions, 57
translating from English, 14troubleshooting
cookbook-style manuals, 134in reference pages, 140manuals, 27
True-Type fonts, 281tutorials, 136
definition, 298example of, 137relation to guides, 138
Type 1 fonts, 281typography (see fonts)
TechnicalWriting.book Page 316 Wednesday, April 20, 2005 2:34 PM
317Index
UU.K. readers and baseball, 15unfortunately (transition), 56units of measurement in tables, 75
Vvariable width fonts, 274variety
changing pace, 122PowerPoint presentations, 234question-and-answer format, 118
VCs (see venture capitalists)venture capitalists, 181verbs, 34
compared to adverbs, 36simplicity of, 14strong, 34tense, 35varying, 35
viruses and hyperlinks, 172visual cues in layout, 104visual learners, 242visualizing audience, 9vocabulary of non-native speakers, 14
Wwarranty cards, 24weather glossary, 152weather station doc spec, 23Web pages
associating related, 174brevity, 174definition of, 298fonts, 278height of, 174plan for a Web site, 162secondary, 174subheads, 175summary, 180templates, 168, 169vs. traditional documentation, 175width of, 174writing for, 175
Web sites, 161–180color, 167
comparison to paper medium, 161creating list of pages, 162definition of, 298dynamic content, 163home pages, 162, 164hyperlinks in body text, 172introduction, 164layout, 104mysteries, 166navigators, 170page templates, 168, 169planning, 162purpose of, 162search engines, 165secondary pages, 162static content, 163summary, 180title of, 164, 165tone, 167vs. television, 166
weight of fonts, 272, 273which (word usage), 41white space, 107
definition of, 298enhancing, 108layout, 107Web sites, 167
width of Web pages, 174Winky the Deer, 126women and color blindness, 95word usage
above, 69adverbs and adjectives, 36affect, 42below, 69can, 41effect, 42employ, 14following, 69happen, 34he, 37it, 37it’s, 42its, 42occur, 34okay, 15preceding, 69pronouns, 38she, 37
TechnicalWriting.book Page 317 Wednesday, April 20, 2005 2:34 PM
318 Index
word usage (contd.)that, 41then, 67there is, 34to be, 34use, 14utilize, 14wasteful vs. frugal, 40which, 41you, 38
wordsfor experts, 32jargon, 32
length of sentence, 50summary of, 43
writer’s block, 128writer’s relationship with editors,
260writing style, and editors, 259
Yyou (word usage), 38
technical journals, 114You are here signs, 92
TechnicalWriting.book Page 318 Wednesday, April 20, 2005 2:34 PM