Symbols -...

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


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 03 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


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


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


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


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)


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


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


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


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)


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


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)


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


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)


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


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


Symbols -...

Documents

Transcript of Symbols -...