Verbs 34
Adjectives and Adverbs 36
Pronouns: He, She, and They 37
Pronouns: You 38
Pronouns: It and They 39
Fluffy Phrases 40
Commonly Confused Words 41
Summary of Words 43
CHAPTER 5 Sentences 45
Active Voice and Passive Voice 46
Active Voice Is Better 47
When Is Passive Voice Okay? 48
Short = Sweet 49
Causes of Long Sentences 50
One Sentence = One Thought 51
Parenthetical Clauses 52
Summary of Sentences 53
CHAPTER 6 Paragraphs and Sections 55
Sentence Transitions 56
Paragraph Length 58
Paragraph Transitions 59
Sections 60
Summary of Paragraphs and Sections 61
CHAPTER 7 Lists 63
Bulleted Lists 64
Elements in Bulleted Lists 65
The Length of Each Element 66
Numbered Lists 67
Directions 68
Introductions to Lists 69
Parallel Lists 70
Summary of Lists 72
CHAPTER 8 Tables 73
Column Headers 74
Units of Measure 75
Arrangement of Columns and Rows 77
Contents
Parallelism in Tables 79
Amount of Text in Cells 80
Rules 81
Shading 82
Captions 83
Summary of Tables 84
CHAPTER 9 Graphics 85
Time Series 86
Extra Detail in Online Graphics 88
Before and After 89
Callouts versus Embedded Text 90
Graphics That Orient Readers 92
Screenshots 93
Color Blindness 95
Block Diagrams 97
Text That Supplements Figures 99
Technical Photography 100
Line Art Enhances Technical Photographs 101
Big Picture First, Then Details 102
Layout: Controlling Focus 104
Layout: Keeping Eyes on the Page 106
Layout: White Space 107
Summary of Graphics 109
CHAPTER 10 Professional Secrets Ill
Explanations of Formula-Based Rules 112
Examples 114
Examples by Metaphor 115
Examples for Programming Documentation 116
Question-and-Answer Format 118
Question-and-Answer Format (example) 119
In Other Words 120
Tone 121
Pace 122
Footnotes and Other Digressions 123
Beyond the Obvious 125
Precision Descriptions 126
The Hardest Part of Writing 128
Summary of Professional Secrets 129
Contents xi
CHAPTER 11 Manuals 133
Manual Style: Cookbooks 134
Cookbook Example: Installing the Carambola Server 135
Manual Style: Tutorials 136
Tutorial Example: Getting Started with HTML 137
Manual Style: Guides 138
Guide Example: Creating HTML Headers 139
Manual Style: Reference Manuals 140
Reference Example: The prime Utility 141
Manual Style: Nonverbal Manuals 142
Online Help: Overview 143
Online Help: Best Practices 144
Online Help Examples 145
Release Notes 147
Release Notes Example: Carambola Web Server Version 3.7 148
Prefaces 149
Preface Example 150
Glossaries 151
Glossary Example: Tropical Weather Terms 152
Tables of Contents 153
Indexes 155
Indexes: Providing Concise Entries 156
Indexes: Permuting Terms 157
Indexes: Providing Entries for Concepts 158
Summary of Manuals 159
CHAPTER 12 Web Sites 161
Plan Your Web Site 162
Home Page: Specify Purpose and Audience 164
Home Pages: Engage the Reader's Imagination 166
Home Pages: Set the Tone 167
Page Templates 168
Navigators and Search Boxes 170
Hyperlinks in Body Text 172
Secondary Pages 174
Text in Web Sites 175
PDF versus HTML 176
Frequently Asked Questions (FAQs) 178
Summary of Web Sites 180
i
xii Contents
The Proposal before the Proposal 182
Adherence to the Proposal Template 183
Proposal Element: Cover Letters 184
Proposal Element: Biographies 185
Proposal Element: Abstracts 187
Proposal Element: Contingency Plans 188
Proposals for Revolutionary Ideas 189
Research Proposals 190
Research Proposals: Significance Statements 192
Research Proposals: Objectives and Hypotheses 193
Research Proposals: Design and Methods 194
Book Proposals 195
Book Proposal: Example Marketing Section 197
Business Plans 198
Summary of Proposals 200
CHAPTER 14 Internal Planning Documents 201
Business Proposals 202
Business Proposal: Example 204
High-Level Technical Specs 206
High-Level Technical Spec: Example 208
Low-Level Technical Specs 210
Low-Level Technical Spec: Example 211
Summary of Internal Planning Documents 213
CHAPTER 15 Lab Reports 215
Abstract 216
Introduction 217
Materials 219
Experimental Procedure 220
Results 221
Discussion 223
Conclusion 224
References 225
Summary of Lab Reports 226
CHAPTER 16 PowerPoint Presentations 227
Organizing a Presentation: The Big Picture 228
The Number of Slides 229
The Opening Moments of a Presentation 230
Introductory Slides: The Traditional Approach 231
Contents xiii
Body Slides: Face and Variety 234
Mechanics: Fonts and Backgrounds 235
Body Slides: Effective Lists 236
Audience: The Theory of Relativity 238
Graphics 239
The Complexity of a Graphic 240
Question-and-Answer Sessions 241
Different Kinds of Learners 242
PowerPoint Speech: The Basics 243
PowerPoint Speech: Lessons from the Pros 244
PowerPoint Speech: Overcoming Fear 246
Summary of PowerPoint Presentations 247
CHAPTER 17 E-Mail 249
The Essence of the E-mail Problem 250
Before Hitting the Send Button 252
After the First Miscommunication 254
Summary of E-mail 256
SECTION 4 Editing and Producing Documents 257
CHAPTER 18 Editing and the Documentation Process 259
Editing: What Is It Really? 260
Technical Editing a Peer's Work 261
Technical Editing a Superior's Work 262
Copyediting a Colleague's Document 263
Copyediting Your Own Document 264
Media for Technical Editing 265
Bug-Tracking Systems 266
A Process for Editing 267
Beta Tests for Documentation 268
Summary of Editing and the Documentation Process 269
CHAPTER 19 Fonts and Typography 271
Serif and Sans-Serif Fonts 272
Fixed-Width versus Variable-Width Fonts 274
Serif and Sans-Serif in Hard Copy 275
Serif and Sans-Serif in Soft Copy 276
Font Height 277
Italics and Boldface 279
Contents
True-Type versus PostScript Fonts 281
Summary of Fonts and Typography 282
CHAPTER 20 Punctuation 283
Commas 284
Dashes and Hyphens 285
Semicolons 286
Periods 287
Colons 288
Quotation Marks 289
Glossary 291
Bibliography 299
Index 301
Contents xv
Preface
Ihe character of Fortuna—brilliant, sexy heiress to the Gambini empire, and two-time winner of both the Grand Prix de Monaco and the Fields Prize in mathematics—is strictly fictional. In fact, all the characters in this book—whether living or dead, implied or extrapolated, fictional or nonfictional—are fictional. The people, the companies, the situations, and everything presented as 100% factual are completely fictional. In fact, I don't even really exist; "Barry Rosenberg" is just a composite author formed by the publishing company from several actual technical authors.
To be completely honest, this book contains no character named Fortuna. All that stuff about everything being fictional is fictional. The information in this book is the truth and factual and asymptotically approaches satisfactual. I'm real, too. I'm a real technical writer, manager, and teacher working in the software industry. I occasionally teach technical writing to engineering and science students at a surreal place called MIT.
Who Should Read This Book?
I've aimed this book at engineers and scientists who must write about stuff.
Perhaps you are an esteemed 60-year-old scientist who has long realized how integral writing is to the job. Perhaps you are a 20-year-old science student who is taking sa class in technical writing because "you have to." Perhaps your career is somewhere between those two points, and you find it painful to write the specs and reports that your job requires, and you are sick of your peers scribbling "I don't understand" in the margin of everything you write, and you just wish that there were a way to make writing go a little easier.
Perhaps you are already a good writer and would like to take your writing to another level.
Let me re-emphasize: this book is for engineers and scientists, not professional writers. I've assumed that you don't much care about the difference between transitive and intransitive verbs—you only want to write better. If you'd like to find out more about the demographics for this book and who I think you are, see Table 2-1.
1. Much the same way that a nineteenth-century publishing syndicate formed "Mark Twain."
Preface
How Is This Book Organized?
I've organized this book into the following four sections:
• Section 1 introduces the field and explains how to plan documentation.
• Section 2 teaches you the nuts and bolts of technical and scientific writing.
• Section 3 explains how to write particular kinds of engineering and scientific documents.
• Section 4 covers editing and producing documentation. The book concludes with a glossary of writing terms. Section 1 contains the following chapters:
Section 2 contains the following chapters:
1
xviii Preface
Section 3 details specific kinds of documents. It contains the following chapters:
Section 4 contains the following chapters:
What's Unusual about This Book?
This book—like the other books in the Spring Into... Series—provides the following eccentricities:
• Each topic is explained in a discrete one- or two-page unit called a chunk.
• Each chunk builds on the previous chunks in that chapter.
• Most chunks contain one or more examples. I believe that good examples provide the foundation for almost all useful technical documents.
• Many chunks contain sidebars and "Quantum Leap" sections, which provide helpful, if sometimes digressive, ancillary material.
Preface
1 assume that you are a very busy person for whom the time spent in the very act of buying this book was excruciatingly painful. To repay that incalculable opportunity cost, I've adopted the chunk style of presenting information so that you can learn as rapidly as possible.
Finally, I hope you'll find this book fun to read. If you've paid good money for a book— no matter what the topic—boring text is a slap in the face.
Writing a Book about Writing Books
I had this great cognitive psychology professor as an undergraduate. Three times every week, he lectured us on current research on memory. Without fail, in the middle of every lecture, he ran back to his office to fetch the notes he had forgotten. He followed in the same vein as my acne-scarred dermatologist, my cross-eyed opthamologist, and my sister's speech pathology professor, who had a regrettable stuttering problem.
All those people haunted me while I wrote this book. I kept wondering whether I was the writing professor who couldn't write well. After writing each sentence, I stepped back and asked, "Am I practicing what I'm preaching?" Friends, it got ugly. I'd write a sentence, then erase it, then rewrite it, and erase it, and on and on it would go. Writing suddenly became very difficult for me. My self-doubt reached biblical proportions.
Then it hit me—I had become the audience. I had re-experienced the pain of writing. This was a breakthrough because "becoming the audience" is one of the most important states a technical or scientific writer can achieve. Yes, pain is good.
May I write about something else now
S
Where Can You Download Examples Used in This Book?
You can download a subset of the examples from this book by browsing to the following URL:
http://www.phptr.com/title/0131498630
What Is Fake in the Examples?
I am honor bound to proclaim the following disclaimers about the examples:
• All of the companies mentioned (Dexco Unlimited, Carambola Publishing, Pravda Mills, Googieplex, Calispindex, and so forth) in this book are figments of my imagination. If I accidentally picked the name of a real enterprise, then it was purely a coincidence.
• The sample biographies used in this book are of fictitious people.
• The sample proposals and lab reports exist solely to teach you how to write better proposals and lab reports; they are not based on real proposals or real experiments.
Preface
Who Helped Me Write This Book?
Mark Taub—the publisher of this book—wisely appointed the following three primary reviewers, all of whom were completely amazing:
• Mary Lou Nohr—brilliant wit of technical editing—who turned out beautifully detailed and highly humorous responses to my drafts. Mary Lou's comments were, themselves, of publishable quality.
• Chris Sawyer-Laucanno—poet, biographer, expert in ancient languages, and technical writing professor at MIT—who offered insightful and crucial criticism.
• Nicholas Cravetta—engineer and writer—whose tough love kept me on the straight and narrow.
Much of the material in this book originated from a technical writing course I taught for four semesters at MIT. I am indebted to Jim Paradis, Les Perelman, and Steve Strang for giving me the opportunity and the guidance to teach that course.
Julie Nahil did a wonderful job guiding this book through its final editorial phases.
Other material in this book comes from conversations with great technical writers, including Jim Garrison, Marietta Hitzemann, John Abbott, and Judy Tirutz. Special thanks to Kenyon College and to the technical writing department at Rensselaer Polytechnic Institute for preparing me for the technical writing life. Thanks also to Roger Stern and Arthur Lew-bel for random props, information, and jokes. Gigantic thanks to the brilliant engineers at 170 Systems who served as the inspiration for much of this book.
Finally, enormous thanks to my wife Marilyn, who took care of far too many day-to-day details over the last year so that I could have the time to write this book.
Preface xxi
SECTION 1
Planning to Write
t "if
ihis section introduces the field of technical and scientific writing, then explains how to evaluate your target audience. It concludes by showing you how to write professional specifications for the documents you plan to write.
'£■■
CHAPTER 1
The Quest
\hen I meet someone at a party and say that I'm a technical writer, there is never a follow-up question. After an awkward silence, the person standing next to me invariably becomes the center of attention. ( You shuck oysters for a living? How perfectly droll! Do tell us more. )
And yet, good technical and scientific communication is one of the building blocks of civilization. Preserving discoveries through writing means that others can benefit from them. Inventing life-saving pharmaceuticals is useless without clear descriptions of how to fabricate and use them properly. How many wonderful discoveries have been lost because a scientist or engineer didn't or couldn't successfully describe the idea? How many commercial ideas have failed because no one could explain how to use the product? How many ideas have failed because readers were bored instead of inspired?
When teaching technical writing to science and engineering students, I've heard them voice concerns such as the following:
• / like writing fiction, but technical writing is really uncreative and dull. Indeed, technical writing can be dull, but it doesn't have to be.
• Engineers and scientists cant write. This is a "truism" that just isn't true. In fact, many technical people write beautifully.
• Writing is really hard. Okay, this one is true.
Is
The Quest 3
Technical Writing Theorems
If you asked a professional technical writer to recite the key principles of technical writing while standing on one foot, she would probably say something like the following:
• Write appropriately for your audience.
• Write clearly.
• Write concisely.
• Engage your audience.
• Help the reader.
These theorems often conflict with each other. How, for example, can you describe something accurately while staying as concise as possible? How do you engage your target audience while describing something as dry as dust? To solve these conflicts, you'll need to enhance a seemingly conflicting pair of skills—creativity and discipline.
Technical writing offers few theorems. These theorems lead to only a few dozen corollaries. For example, the "write concisely" theorem leads to corollaries such as the following:
• Keep sentences short by eliminating unnecessary words.
• Write sentences primarily in active voice.
• Eliminate unnecessary sentences or irrelevant concepts.
Since technical writing offers so few fundamental theorems and corollaries, it would seem to be an easy art to master. Although, if you were to apply this same logic to painting, you could become an expert painter simply by mastering three colors and a few kinds of paint brushes. As with painting, though, correct application of the simple theorems takes years of guided practice. This book offers a good start, but it is only by practicing with an experienced editor that you will truly learn to write well.
The following ditty—a paraphrase of a famous quote on diplomacy by Isaac Goldberg— summarizes your quest:
1
Technical communication is to write and to say The geekiest things in the simplest way.
The Quest > Technical Writing Theorems
Technical Writing Can Be Creative
Technical and scientific writing has a well-founded reputation for being dull. Consider the following passage, which is aimed at lay readers:
Hot air is less dense than cold air. When you put hot air on a scale, it weighs less than cold air. Consequently, hot air rises and cold air sinks. Since hot air and cold air frequently come into contact with each other in the atmosphere, a lot of mixing of air results, which can cause interesting reactions.
The preceding passage meets a few of the criteria for good writing. It is fairly appropriate for the target audience (though lay readers might have trouble imagining the weight of air pressing against a scale), and it is concise. However, the biggest sin in the preceding passage is that it does not engage the audience. It produces no spark; you can almost hear the reader snoring.
Despite its reputation, technical and scientific writing can be highly creative and engaging. It is really a matter of mind-set—you must truly feel the obligation to go beyond a dry recitation of facts to provide a treat for your audience. Injecting life into the preceding passage yields the following:
Did you ever watch a hawk fly over a highway on a hot day? He flies so easily, barely beating his wings at all. That's because the air over the highway is very hot. Since hot air rises, the hawk gets a free ride up. Conversely, cool air sinks. So, when the hawk flies over cooler terrain, he has to beat his wings extra hard.
On a larger scale, when a big mass of hot air meets a big mass of cold air, our hawk must take shelter from stormy weather.
The second passage is far more engaging than the first for the following reasons:
• Air is too abstract to visualize, but a hawk bobbing up and down on the air is easy to visualize.
• Many readers find stories about animals compelling.
• The image of the soaring hawk provides a mnemonic device for this lesson. For all forms of communication, remember this lesson:
You cannot impart information unless you have the audience's attention.
The Quest > Technical Writing Can Be Creative
Tell 'Em
I saw a famous folksinger in concert a few years ago. Although he has had a wide-ranging career spanning many decades and musical styles, his name is instantly identified with a single song that he wrote long ago. In concert, he sang a few songs and then mentioned that—before he could continue—he had "a little piece of business" to attend to. Then, with his face twitching, he scratched out a limp rendition of his most popular song.
Before continuing, there is a little piece of business that I must attend to. It goes something like this:
1. Tell 'em what you're going to tell 'em.
2. Tell 'em.
3. Tell 'em what you told 'em.
The preceding ditty—a folksy version of "introduction, body, conclusion"—is undoubtedly technical writing's greatest hit. Many engineers and scientists recite this formula with an "F = ma" certainty. It is a useful formula for organizing writing at the following levels:
• At the book level, the opening chapter should introduce the book and the closing chapter should summarize the book's contents.
• At the chapter level, the opening section should introduce the chapter's topic and the closing section should summarize the chapter.
Some writers use this formula right down to the paragraph level. Indeed, in certain kinds of writing, paragraphs do benefit from a classic strong opening and closing sentence. However, good technical prose emphasizes speed, so the formula imposes too much baggage to be practical at the paragraph level.
Experimentation shows that audiences tend to remember facts presented at the beginning and the end of a session better than in the middle. Thus, it is a sound idea to highlight key principles in both the introduction and conclusion. Furthermore, repetition is essential for learning.
The downsides to this formula are as follows:
• Repetition is not concise.
• Many writers produce wasteful conclusions that are almost identical to the introduction.
• Many readers now skip over summary sections (except in lab reports).
i
The Quest > Tell 'Em
The Value of Technical Communication to You
The difference between success and failure in the technical world is generally the ability to communicate effectively.
In engineering and science, brilliant does not always equate to successful. In fact, brilliant often equals frustrated. Of course, success is a very tricky concept to define—one engineer's success might equal another's failure. Nevertheless, I'll define engineering success as having one or more of the following parameters:
• The engineer is promoted to a management position.
• The engineer is paid significantly more than his or her peers.
• The engineer invents something that changes the world in a positive way.
• The engineer generally gets his or her way in technical disagreements. (Some engineers find this parameter more precious than oxygen.)
In my opinion, successful engineers convey their ideas better than unsuccessful engineers. Top management positions in engineering organizations are staffed by those who communicate more effectively and more persuasively than their brilliant colleagues. Due to the rising use of e-mail and instant messaging in technical organizations, writing clearly and concisely has never been more important.
The Quest > The Value of Technical Communication to You 7
Comparing Technical Writing to Engineering and Science
Technical writing shares the following similarities with engineering and science:
• Successful projects require careful planning. Good engineering teams produce detailed engineering specifications prior to implementation. Good technical writers produce detailed documentation specifications prior to writing.
• Successful projects require testing. Good engineering projects run beta tests to find defects in early versions of the product. Good technical writers beta test early versions of documentation for feedback.
• Successful projects require iteration. No matter how much planning precedes implementation, engineering typically requires a certain amount of iteration to achieve perfection. An old documentation adage recursively states, "Writing is rewriting." Good writers and good engineers constantly ask, how can I improve this?
• The principle of parsimony is paramount. In both engineering and technical writing, simpler is better.
• Achieving parsimony is difficult. Elegance is not cheap. For example, in software engineering, it usually takes much longer to code an algorithm in 100 lines than in 200 lines. Similarly, it can take a lot longer to document a complex idea in 100 pages than in 200 pages.
Technical writing differs from science in the following ways:
• Writing cannot be successfully reduced to formulas. The goal in most sciences is to create mathematical equations that model and predict phenomena. In technical writing, although readability formulas can estimate a passage's audience level, no formula can predict whether writing is clear. Ultimately, the only true test of a document is getting humans to read and act on it.
• Writing and science require different thought processes. Scientists construct paradigms from variables and constants. Writers construct documents from words. Both pursuits are logical, but the two disciplines use different parts of the brain. Scientists seek objective logic; writers seek a subjective empathy with their readers.
i
8 The Quest > Comparing Technical Writing to Engineering and Science
CHAPTER 2
Audience
ealtors have an old joke that goes something like this:
Q: What are the three most important things in real estate?
A: Location, location, and the third one isn't really that important.
The technical writing variant on the joke is as follows:
Q: What are the three most important things in technical writing? A: Audience.
Get it? See, technical writers are really concise, so... ahh, forget it.' At any rate, identifying your audience's needs is essential for writing good documents. This chapter helps you define your audience through a set of questions, such as the following:
• What does my audience already know about this technology?
• What is the native language of my audience?
If you work for a company, your marketing department should be able to help define your audience. Large companies often have extensive market-research data.
Picturing Your Audience
The concept of audience is too abstract for some writers. To solve this problem, consider pasting a picture of someone in your target audience up on your monitor. Some writers find it easier to write for an individual than for a collection of people.
I. The realtors' version is funnier. I weep for my profession.
Audience 9
General Education Level
i
How much general education has your audience had? Did your audience attend high school? College? Graduate school?
Readers prefer text that is appropriate for their general education level. Writing too "high" makes readers feel dumb. Writing too "low" makes readers feel that they are wasting their time.
Most textbooks on writing tell you to write long sentences for highly educated readers and short sentences for poorly educated readers. However, lengthy sentences have no place in technical prose; the goal in technical writing is always to produce short, clear sentences.
Most textbooks on writing also tell you to use vocabulary appropriate for your readers' educational level. In other words, use a broad, sophisticated vocabulary for highly educated readers and a limited, unsophisticated vocabulary for poorly educated readers. After all, you don't want uneducated readers scrambling for their dictionaries after every sentence.
Many fiction authors often ignore this principle, preferring beautifully ornate words like labyrinth and absinthe to compose sentences such as the following:
The ornately beautiful carriage bumbled chaotically through the morass like a butterfly drunk on absinthe careening through a labyrinth.
The preceding sentence is, indeed, ornately beautiful; however, figuring out what it means (or whether it means anything at all) takes a while. By contrast, good technical prose is built for speed; technical readers do not have the patience to parse exceedingly complex sentences. Nevertheless, if you are comfortable, you can certainly mix in bona-fide "big" words when your audience is well educated. Sometimes a big word is the most concise word since it may spare you from using multiple little words in its place. On the other hand, if your writing vocabulary is somewhat limited, you should not force yourself to use high-falutin words just because your audience is highly educated. In technical writing, the perfect word is often the simplest word.
10 Audience > General Education Level
Experience and Expertise
How much experience does your audience have with this technology or topic? Does your audience already have formal training in this technology?
If your audience is already familiar with the topic, you can start at a higher level than if they are new to it. Never disrespect a trained audience by explaining topics that they have already mastered. When writing for an experienced audience, you can use jargon and acronyms freely. Conversely, if your audience lacks experience, you must carefully define all technical terms. For example, when writing for an audience of professional programmers, the following passage is appropriate:
The product provides an extensive Java API.
Providing the same information to nonprogrammers would yield a passage such as the following:
The product provides an extensive Application Programming Interface (API). Programmers can use this API to extend the features of our product or to integrate other software products with our product. The APIs for our product are written in Java, which is a popular programming language.
Alternatively, many nonprogrammers do not care about technical details, so a passage like the following (which completely omits the acronym API) might be just as effective:
We provide manuals describing how your programmers can extend the product's features. In other words, if our off-the-shelf product isn't exactly what you want, your programmers can customize it.
Sometimes your audience has had plenty of negative experience. Is your audience skeptical of this technology? Never ignore negative expectations. For example, consider the following inoculation from a cell phone manual:
You may have run into problems getting a signal from your previous cell phone. In some cases, this was due to a lack of cell towers. Our continentwide network of cell towers ensures that you are always in range. In other cases, your old cell phone may have lacked the power to transmit a strong enough signal. Thanks to improvements in battery technology, your new cell phone transmits a much stronger signal.
Audience > Experience and Expertise
Breadth of Audience
l:
Are you writing for a tightly focused audience or for a broad range of readers?
In some situations, you can pin your audience down to a fairly precise demographic. For example, when you are writing a lab report on an esoteric topic, all your readers are almost certainly experts on the topic.
In other situations, your audience is rather broad. For example, consider the breadth of audience for a cell phone user's manual. The readers span a wide age and educational background. Some readers have never used a cell phone before, and others have used them daily for 15 years.
In still other situations, the audience's breadth falls somewhere in between. For example, consider a manual explaining how to administer a Windows system. The core audience for this manual will probably be professional system administrators with a fair amount of expertise in Windows. However, many amateurs might also use this manual to learn how to administer their PCs at home.
It is far harder to write for a broad audience than for a narrow one. When writing for a broad audience, you should do the following:
• Aim the bulk of the documentation at the least experienced readers.
• Aim a few advanced chapters or sections at experienced readers. Label these chapters or sections explicitly as "For Advanced Readers."
If time and money are no object, your organization should handle a broad audience by writing two separate documents:
• one aimed at inexperienced readers
• one aimed at experienced readers
12 Audience > Breadth of Audience
Native Language
What percentage of your audience reads English as a native language? How well does your audience actually read English?
Writing for Technologists
English has become the dominant technical and scientific language in the world. Most technologists and scientists worldwide can read English. In many European countries, technical audiences comprehend technical prose written in English almost as well as audi ences in the United Kingdom or United States.
How Pervasive Is English?
Two colleagues—a Danish engineer and a Swedish engineer—hold a weekly teleconference. (Danish and Swedish are similar languages.) I asked the Danish engineer which language was spoken during the teleconference. He replied, "I speak to him in Danish. He answers me in Swedish. And when we are having trouble understanding each other, we speak English."
Many languages—Chinese, for example—are markedly different from English. In such countries, technologists often have more difficulty understanding English text than in European countries. Many nonnative readers will miss nuances. Note that small misunderstandings about technical text can lead to disastrous technical problems.
When writing for a technical audience containing many nonnative speakers, follow these guidelines:
• Follow exact grammatical rules —even the annoying ones. For example, when writing for native speakers, it is okay to split infinitives. However, split infinitives can confuse some nonnative speakers. For example, consider the following passages, which are similar but not quite identical. Version 1 contains a split infinitive but version 2 does not. Nonnative speakers will generally find version 2 far easier to understand than version 1.
1. The filter causes high-frequency notes to gently and sweetly pass.
2. The filter causes high-frequency notes to pass gently and sweetly.
1
Audience > Native Language 13
Avoid uncommon acronyms. (It is fine to use common acronyms.) Native English speakers can often guess the meaning of uncommon acronyms, but such acronyms cause problems for nonnative speakers.
Simplify vocabulary. Generally speaking, nonnative speakers have a somewhat smaller English vocabulary than native speakers.
What Is a Simple Word?
Which of the following verbs is simplest?
• use
• utilize
• employ
Native English speakers will certainly pick "use" as the simplest. It is, after all, the shortest and the most commonly... er... used. Native French speakers, however, might choose differently because the verbs "utilize" and "employ" are cognates for common French verbs.
Writing for Nontechnical Nonnative Speakers
When writing for a nonnative audience of nontechnologists, you cannot assume that your readers understand English. True, many of your readers (particularly Europeans) will understand English very well, but many readers will not. In such situations, your organization must translate the documentation into your readers' native languages.
For example, the documentation set for a large software product might consist of the following:
• Manuals for programmers and system administrators, which do not have to be translated.
• Manuals and online help for end users, which do have to be translated.
In certain situations, documentation can consist entirely of graphics, which would not have to be translated. For example, directions for unpacking a shipping container might be given through pictures only.
li
14 Audience > Native Language
Native Culture
What percentage ot your audience will understand your cultural references?
Writers sometimes mistakenly assume that because readers share the same language, they also share the same culture. The key rules for producing useful technical or scientific prose for a worldwide audience are as follows:
• Avoid slang.
• Pick examples and metaphors that will make sense in multiple cultures.
• Be sensitive to fundamental differences in presentation.
• Don't offend.
Slang
Even among native English speakers, slang is often confusing—Brits, Americans, and Australians do not always understand each other's lingo. (What in the world are bangers and mash anyway?)
Baseball is a huge part of American slang. A sentence such as the following makes perfect sense in baseball-loving countries such as the United States and Japan:
Project Walrus hit a home run for the company.
British readers, of course, would say that a baseball metaphor just isn't cricket.
Many writers feel that soccer/football terms are cross-cultural since the game is "universal." Be aware, however, that many American readers would rather eat a soccer ball than go to a soccer game and that soccer slang is not okay for an American audience.
Okay Is Okay
Mysteriously, just about everyone seems to know the meaning of the American slang word okay or OK. In fact, this word is so okay that it has crept into the slang of other languages.
Audience > Native Culture 15
Examples
Despite assurances to the contrary, it turns out that the world is actually an awfully big place. It is hard to create examples that will make sense everywhere in the world. For example, consider the following seemingly benign passage:
When an electric force is applied, the charge in a capacitor increases, much the way the balance in your checking account increases when you work. Then, when the charge is needed, the capacitor releases it, much the way you release the value in your checking account by writing a check.
Is the preceding example cross-culturally correct? Unfortunately it is not. Personal checking accounts are unknown in Japan. Before investing too much energy in an example, do some research.
An Almost-Universal Cultural Reference
Earthlings do not share a common religion, language, or political system. However, we do share a knowledge of American movies. Many readers are unfamiliar with rock gardens in Kyoto or tea plantations in India, but most know who R2D2 is.
Presentation
We often forget that many daily details are not universal. For example, consider the following date:
1/3/05
American readers interpret the preceding date as January 3, 2005. European readers interpret it as 1 March, 2005. To prevent cross-cultural confusion on dates, it is clearer to spell out the month as in the following example:
1 March 2005
Some countries present monetary values as integers only, while other countries express money with real numbers. Some cultures use commas to separate groups of three digits in a large number, but other cultures use periods. To avoid confusion, you may need to provide multiple examples of the same value.
Don't Offend
Cross-cultural prose tries not to offend. For example, humans in photographs should be modestly dressed, and any food should be vegetarian. Obviously though, you must be practical. For instance, when documenting high-fat diets, it is fine to depict meat.
16 Audience > Native Culture
Audience Motivation
Audiences read fiction because they want to and technical prose because they have to.
Writers often forget to ask themselves why readers are picking up a document in the first place. The following list provides a few general answers:
• People read manuals to learn how to do something. Readers study manuals to learn how to see through a new telescope, cook with a new microwave oven, or write code in a new programming language.
• People read reference manuals to find information very quickly. Audiences often read reference material to recall a fact they already know.
• Scientists read lab reports to keep up with their field, to evaluate colleagues' progress, and to consider their next experimental steps.
When planning a document, always consider your readers' motivations.
What Is Your Audience's Emotional State?
Quickly now—what is the emotional state of someone reading the "How to Change a Flat Tire" section of an automobile owner's manual? How maniacal is the reader who is looking up fatal error codes in the back of a software manual? How well will a patient who has just received a distressing diagnosis be able to comprehend a doctor's instructions?
Entire manuals will never be read until disaster strikes. When writing about troubling situations, remember the following:
• Agitated readers are not always thinking rationally. You might need to start certain sections by reassuring the reader that the current problem is fixable.
• Agitated readers are probably in a highly impatient mood. You must provide concise answers.
To help agitated readers, consider the following suggestions:
• Provide a "Troubleshooting" section in manuals.
• Make sure that various kinds of emergencies have entries in the index and table of contents.
Audience > Audience Motivation 17
Medium and the Message
Is your target audience reading the document in hard copy or soft copy? If in soft copy, does the technology permit hyperlinks? Will people read this document linearly or in a random-access fashion?
I don't honestly believe that the medium is the message. (I lean towards the message being the message.) Nevertheless, the wise writer is aware of the medium through which the document will be read.
One obvious advantage of writing for the Web is that you can provide hyperlinks. With hyperlinks, you can rely on other sources to tell parts of the story. Hyperlinks are particularly useful when your audience is broad. They can redirect newcomers to definitions or introductions without destroying the focus of your prose.
If you are writing for the Web, how will readers arrive at your document? Will they start with your document, or will a hyperlink carry them there? Restating the question, how much will your readers already have read about the topic prior to hitting your document?
Hard copy isn't dead—not yet, anyway. Although paper offers many disadvantages, it does offer much higher resolution than soft copy (up to two orders of magnitude, depending on how you count). Thus, most images will look better on paper than on a Web page. Many readers find long documents much easier to read in hard copy than in soft copy. Also, because of its relative permanence and tangibility, hard copy strikes many readers as being more solid and reliable. Legal transactions generally still require paper. Paper just plain strikes people as being more "real" than soft copy.
Is your audience going to read your document straight through, from cover to cover? Probably not. Modern audiences just do not have the time or patience to read documentation straight through. Most technical readers snack, nibbling on a page here and a chapter there. That is not to say that straight, linear access is dead. Fiction, after all, is still going strong. However, thanks to the World Wide Web, most technical readers prefer random access that takes them straight to the desired fact.
Depending on the medium, you might have the freedom to use attention grabbers such as quotes, sidebars, or photographs to pull in readers.
18 Audience > Medium and the Message
Becoming the Audience
In teaching a task that requires great concentration, teachers sometimes tell students to imagine themselves in the role of the object being manipulated. Thus, the sculptor imagines the sculpture as an extension of herself, and the archer "becomes" the arrow. In technical writing, the wise author periodically becomes the audience. In other words, the author periodically stops writing and starts reading and relating to the prose as the audience would.
Gaining empathy for the reader is probably the hardest skill for a writer to learn. You must simultaneously be of two minds—the expert and the novice. For example, while documenting how to operate a new medical instrument that you invented, you must imagine what it is like to be the doctor who has never seen this device before. You must frequently step back and ask yourself, if I were in this doctor's shoes, would I understand this?
The best way to become the audience is, literally, to become the audience. That is, you must do the things that your audience would do. For example, suppose a software engineer creates a new Application Programming Interface (API). The classic writer's mistake would be to document only how this API works instead of documenting how another programmer would make practical use of it. To document the API, the writer should first become the audience by using the API to code sample real-world applications. In other words, the writer should use the API exactly as her readers would. Through this experience, the writer would learn not only how the product should work, but she would also learn various limitations on using this product.
Walking a Mile in a Reader's Shoes
It is sometimes impractical to become the audience in a literal way. Nevertheless, you can still gain empathy by reading similar documents immediately prior to writing your own document. For example, suppose you must write a spec for your colleagues. Immediately prior to writing, consider reading a couple of old specs that your colleagues wrote. What did you like about their specs? What confused you? What irritated you? When you write your design spec, emulate the good parts and eliminate the bad. Feel the pain so that your readers don't have to.
Becoming truly empathetic is difficult. After all, it is a long round-trip from expert to novice and back again. This is one of the primary reasons that writing is often best done by someone other than the inventor.
Summary of Audience
As you prepare to write, it is helpful to fill out an audience chart such as that shown in Table 2-1. I've taken the liberty of filling it out based on the planning 1 did for writing this book. Note that I had the advantage of extensive market research on the target audience.
TABLE 2-1 Target Audience for This Book
Question
Answer
How much general education has the target audience had?
The target audience on average holds a master's degree, mainly in a technical or scientific discipline.
How much experience does the target audience have with technical or scientific writing?
Everyone in the target audience has had at least some technical writing experience, either at school or at work. A few readers have had a lot of experience. Almost no one in the target audience is an expert.
What is the target audience's predisposition toward the subject matter?
The maiority of readers find technical and scientific writing to be a chore; a smallish minority enjoy it.
Is the target audience tightly focused or broad?
The target audience is reasonably focused in terms of mathematical and analytical aptitude.
What percentage of the target audience reads English as a native language?
Approximately 85% reads English as a native language. The remaining 15% are technical people who are comfortable reading (and writing) English.
What percentage of the target audience will understand my American cultural references?
Approximately 75% of the target audience lives or has lived in North America. Since 25% live elsewhere, I must be careful about cultural references.
What kinds of examples will the target audience prefer?
The target audience prefers scientific examples. However, since the audience comes from a wide variety of disciplines, I should use examples about general scientific principles that most readers will know.
Why is the target audience reading this book?
The target audience wants to enhance its writing skills, perhaps to take care of a specific short-term assignment or perhaps to achieve longer-term career goals.
20 Audience > Summary of Audience
CHAPTER 3
Documentation Plans
jf ost professional technical writers produce the following two types of documentation plans:
• documentation specifications (doc specs), which detail a single document
• documentation project plans, which detail a set of documents
Documentation professionals ostensibly write these plans to provide a formal feedback mechanism for other people in an enterprise. In other words, these plans provide a way for the head of engineering or a marketing representative to sway what will be written before it is written. Indeed, some organizations really do review documentation plans very carefully and integrate their review into the broader engineering development cycle. However, my experience suggests that you should write documentation plans for a more valuable reason:
Documentation plans lead to better final documents.
Even if no one reads them (hey, it could happen), writing detailed documentation plans will still help you, the writer.
This chapter teaches you how to write both kinds of planning documents.
Documentation Plans 21
Document Specifications (Doc Specs)
Before writing a document longer than 25 pages or so, you should create a document specification (doc spec). A good doc spec serves the following three purposes:
• It helps you organize your thoughts about the document.
• It communicates your intentions to the other members of the engineering team.
• It helps your team reach consensus on the purpose and scope of the document before you start writing. The engineering adage about measuring twice and cutting once also applies to documentation.
Ideally, creating a doc spec involves the following three-step process:
1. You create a preliminary doc spec.
2. Your reviewers analyze the preliminary doc spec.
3. You generate a final doc spec based on your reviewers' comments. If your reviewers disagree with each other, hold a meeting to iron out differences.
Doc specs need not be long. In fact, short doc specs generally yield a better harvest of comments than long ones. A doc spec for a 50-page manual should only be about two or three pages long. A doc spec for a longer manual should be only slightly longer (due to lengthier outlines). Each doc spec should contain the following sections:
• a brief overview of the project
• a detailed description of the target audience
• a brief description of the nongoals—topics that won't be covered in the document
• a section entitled "What Readers Will Know after Reading This Document
• an estimate of the length of the final document
• the tools you will use to write the document, plus the document's output media (PDF, HTML, and/or hard copy)
• optionally, a brief discussion of some of the finer points, such as tone and pace
• a fairly detailed outline, preferably down to first-level heads within each chapter
• a list of reviewers and their responsibilities
• outstanding issues
• a schedule (omitted from the sample doc spec that follows)
lit
22 Documentation Plans > Document Specifications (Doc Specs)
Doc Specs: Sample
Our engineering team plans to roll out the Carambola 3000 Weather Station in May. This doc spec describes a manual entitled Installing the Carambola 3000 Weather Station.
Target Audience
We are aiming the 3000 at the high-end amateur market. This market is split as follows:
• About 80% of this market consists of hobbyists who are serious enough to spend about $200 on a high-quality weather station.
• About 20% of the audience consist of community organizations such as schools that need a weather station but do not have the budget for a professional model.
The hobbyists know what they are doing mechanically; most of them will look at the schematic diagram and skip the text. The community organizations will require the detailed text.
The reader must also install and configure the software. We assume that all readers are comfortable installing software from a CD onto Microsoft Windows; however, we do not assume any knowledge of computers beyond that. So, the guide must patiently explain configuration.
Nongoals
Our target audience already understands meteorological concepts, so the book will make no attempt to explain weather terms or weather forecasting.
What Readers Will Know after Reading the Manual
After reading this manual, readers will know how to do the following:
• Install the tangible parts of the weather station.
• Install and configure the accompanying software.
• Troubleshoot a malfunctioning weather station.
Length
The book will consume approximately 40 pages, including the front and back matter.
Tools and Output Media
We will write the book with Adobe FrameMaker 7.1 and produce diagrams with Microsoft Visio Professional 2000. After finishing, we will generate a PDF, which we will FTP to our
Documentation Plans > Doc Specs: Sample 23
print vendor. Our print vendor will produce an initial run of 3,000 copies on a 6.5 X 9 trii with a wire-o binding. We will kit the manuals with the product on the assembly floor.
Outline
The following is the preliminary outline (subject to change):
• Front matter (title page, copyright page, table of contents, preface)
• Chapter 1: Overview
- Capabilities
- List of Parts
- Schematic Diagram
• Chapter 2: The Weather Station
- Control Box and Power
- Anemometer Unit
- Hygrometer/Thermometer/Barometer Unit
- Rain Gauge
• Chapter 3: Software
- Installation
- Basic Configuration
- Connecting to the Internet
• Appending A: Troubleshooting
• Back matter (index, tear-out warranty card)
Reviewers
The following people have been graciously volunteered to review the manual:
• Eswar will review Chapter 1 and 2.
• Andy will review Chapter 3 and Appendix A.
• Martina will perform a literary edit.
Outstanding Issues
We cannot write Chapter 3 until the software has been developed. Given the software development schedule, we will have limited time to write Chapter 3.
Marketing must finalize the new tear-out warranty card and terms prior to October 15.
1
24 Documentation Plans > Doc Specs: Sample
Documentation Project Plans
A doc spec details a single document; a documentation project plan summarizes an entire documentation set, explaining how different pieces of the puzzle fit together. If your team is writing multiple documents, you should create a documentation project plan. Like a doc spec, a good documentation project plan communicates your intentions to the rest of the team and helps bring the team to consensus.
One way to plan a documentation set is to identify all the audiences you must satisfy and then to figure out which title(s) they need. In the best possible world, each type of user would find everything in a single title. However, this is not always possible. For example, the same audience often needs different kinds of information at different stages, which necessitates multiple titles.
Another way to plan a documentation set is to use a spreadsheet as follows:
1. Create a comprehensive list of everything that users need to do, one item per row.
2. In a separate column, identify the audience for each row.
3. Sort the rows by audience.
4. Group all the items related by audience into a title, or possibly, into multiple titles.
How Many Documents Are Best?
Many companies create more titles than necessary. Smart companies minimize the number of titles. You might well ask, why would creating five 200-page books be better than creating ten 100-page books? Producing and maintaining a title (any title, regardless of length) generates various fixed costs, so reducing the number of titles will reduce the total cost.
A documentation project plan needs to express the following:
• the titles in the documentation set, preferably arranged by target audience
• a few sentences about each title
• a media plan, explaining how each title will be delivered to the target audience
• any outstanding issues
• a schedule (omitted from the sample documentation project plan that follows)
Documentation Project Plan: Sample
Our engineering team plans to roll out the Carambola 3000 Weather Station in May. This documentation project plan summarizes the planned documentation set for the product.
The Documentation Set
The documentation set will consist of the titles listed in Table 3-1.
TABLE 3-1 The Titles in the Carambola 3000 Weather Station Documentation Set
Full Title
Title Abbreviation
Customers
Planning for the Carambola 3000 Weather Station Planning
Installing the Carambola 3000 Weather Station
Installing
We detail each of the preceding titles in separate doc specs, which you can find on the corporate intranet.
For Consumers
We will provide the following three titles for customers:
• Planning —This guide will help consumers prepare for an installation during the three-week interim between ordering the station and receiving it. This guide will help consumers determine the most effective locations for instruments.
• Installing —This guide will help consumers install the hardware and to install and configure the software.
• Release Notes —These notes will summarize the features of the product and detail any known bugs. (For subsequent releases, Release Notes will also document bugs fixed.)
For Integrators
We will provide the following single title for integrators:
26 Documentation Plans > Documentation Project Plan: Sample
• Developing —This is a guide that will detail our APIs for companies that want to integrate the Carambola 3U00 with their products (for example, with factory automation software). This book will contain several example programs written in Java.
Customer Support
We will provide the following documentation for our own customer support organization:
• Advanced Troubleshooting —This guide will explain how to handle various potential customer complaints. Note that the Installing manual also contains a "Troubleshooting" chapter, but the Advanced Troubleshooting guide contains solutions (including remote debugging) that require more sophisticated knowledge of internals.
Although we will target Release Notes for consumers, we believe that customer support will also find them helpful.
Manufacturing
We will provide the following information for our manufacturing and procurement teams:
• Schematics —These will consist of highly detailed schematic diagrams; our manufacturing team requires these schematics to assemble the product.
• Specs —These documents contain tolerances and specifications for all hardware components; our procurement department requires these documents.
Media
We will ship documents in the formats listed in Table 3-2. TABLE 3-2 How We Will Distribute the Documentation Set
Issues
We've never used the print vendor before, and we're a little worried about quality.
Documentation Plans > Documentation Project Plan: Sample 27
Summary of Documentation Specifications
Before sending out your doc spec for review, ask yourself the following questions:
• Are the right people on your distribution list? Will anyone be offended if he or she is not on the distribution list? Conversely, do you have too many people on your distribution list? (If you put too many people on the list, then many readers will not bother reviewing the doc spec because they will assume that someone else will do it.)
• Is the schedule achievable? Can you really write a first draft that quickly? Have you ever written documents of this size before? If not, give yourself plenty of cushion— writing might take longer than you think. Have you allotted a suitable amount of time (not too long and not too short) for others to review this document?
• Does your outline contain all the topics that your target audience needs? Are the topics appropriate for your target audience, or are the topics too hard?
Before sending out your documentation project plan for review, ask yourself the following questions:
• Does your documentation set cover all audience segments?
• Do you have the right amount of information for each segment of the target audience? In other words, does the proposed documentation set meet the needs of all segments? Typically, the honest answer to this question is no. In this case, does the documentation set meet the needs of the primary segment?
• Can your team write all the specified documentation in the allotted time?
QUANTUM LEAP
When the engineering project changes, don't forget to update your documentation plans.
1
28 Documentation Plans > Summary of Documentation Specifications
SECTION 2
Writing: Genera Principles
<■■■■■ i
his section explains the general principles of technical and scientific writing, from sections and paragraphs right down to sentences and individual words.
CHAPTER 4
Words
i he writer's section of your local bookstore contains several lengthy books discussing proper word usage. The erudite writers of these books can spill tankers of ink explaining the many true meanings of the verb "to lie" or the creamy origins of the noun "seersucker." If you intend to get into this writing thing, reading one of these books will give you an appreciation for the subtleties of words and the obsessive requirements of the writer's work.
Why must you obsess about picking the right words in technical prose? In our litigious world, entire lawsuits hinge on improper word usage. Beyond crime and punishment, picking the wrong word in a manual can cost your enterprise a fortune in customer support. Conversely, picking the right word can unlock all sorts of new value in your inventions or ideas.
This chapter focuses on word choice in technical and scientific writing.
■I Words 31
Jargon
1
Jargon is terminology used by experts for experts, that is, words and phrases that practitioners use to communicate within a particular field. When writing for other experts, you must use jargon. Without jargon, you'd be perpetually redefining ideas that your readers already understood. With jargon, you can just blurt out "capacitor," and your electrical engineer readership will know exactly what you're talking about.
The hard part to remember is that your lay audience does not speak jargon. (Hey, that's what makes them the lay audience in the first place.) Frequently, jargon is so ingrained in the way you speak and write that you no longer perceive jargon to be jargon. You may also find it hard to remember who your jargon-speaking peers are. For example, your fellow engineers all understand jargon, but will your manager understand the latest terms? Remember that most managers no longer perform feats of engineering every day, so although they'll understand a perennial like capacitor, they might no longer understand the latest terms.
Jargon Is a Dynamic Designation
Some words bob up and down between jargon and general use. Consider the word transistor. When transistors were first invented, this word was clearly electrical engineering jargon. Then, in the 1960s, cheap transistor radios flooded the American market, and the word transistor was on everyone's lips. Although lay people didn't know exactly what transistors did, they generally understood that transistors helped miniaturize gadgets. Since the 1980s, the term transistor has retreated into jargon, while solid-state terms like CPU and RAM have transitioned from jargon into everyday use. If you don't believe it, look at the computer ads in newspapers and lay magazines. These ads describe a CPU's clock speed and the amount of RAM without having to explain what these terms mean.
To define jargon for a lay audience, do either of the following:
• Define the term in place; that is, define the term when you use it for the first time.
• Defer the definition to a glossary.
For example, consider the following in-place definition:
Our tuner contains 50 frans/stors, which are tiny circuits that boost weak signals into strong signals. A transistor can turn a whisper into a scream.
32 Words > Jargon
Consistency
Renaming a part in midstream will drive your readers crazy; use the same name for the same part throughout the document. For example, if you refer to a certain part as a "widget" in Chapter 1, don't refer to that same part as a "gadget" in Chapter 2. Once a widget, always a widget. Remember that case is also part of a name. Therefore, you must be consistent in how you represent the case of a name. For example, a widget cannot suddenly become a Widget or (horrors!) a WIDGET because some readers will suspect that these are different parts.
It is even more confusing to give two different parts the same name. For example, never refer to one part as the thingy and then to a completely different part as the thitigy. Overloading is useful in programming but awful in technical communication.
Many of you are probably thinking that the preceding two paragraphs are just common sense and that no engineer or technical writer would do such a thing. In fact, overloading and renaming errors are present in almost every technical manual. Oftentimes, it isn't the writer's fault—sometimes the fault lies with the people who originated the names in the first place.
Acronyms provide another prime opportunity for overloading, inconsistency, and confusion. For example, I once worked at a company that overloaded the acronym PS to symbolize four different products or technologies. As you can guess, an acronym should only symbolize one entity.
When new writers learn about the importance of variety in writing, they often oscillate between a technology's full name and its acronym. When you first introduce a term, you should also introduce its acronym, as in the following example:
A Relational Database Management System (RDBMS) uses a table metaphor to store data in rows and columns.
After the initial use, you should pick one version—the more natural version—and use it exclusively. For example, the acronym RDBMS is far more natural than the expanded version, Relational Database Management System.
lit Words > Consistency 33
Verbs
When picking verbs, follow these guidelines:
• Choose strong verbs.
• Avoid overusing forms of to be.
• Provide variety in your choice of verbs.
• Use the same tense throughout the document.
Choose Strong Verbs
Strong verbs pack muscle and energy, moving the reader into action. Strong verbs are specific, precise, and dynamic. Weak verbs lie listless and dormant, generating boredom and sloth. Avoid the following famously weak verbs:
• to occur
• to happen
The preceding generic verbs don't convey anything specific—they just happen. Compare the following variants, noticing how much more powerful version 2 sounds than version 1:
1. If you spread organic compost and limestone, bigger vegetables will occur.
2. Spreading organic compost and limestone generates bigger vegetables.
Avoid Overusing To Be
Although the verb to be is fundamental and essential, you must not overuse it. Many writers reach for it automatically just because it is so handy. Note that to be simply exists; it does not describe.
Many writers team up to be with the generic noun there to produce there is or there are. This combination is very weak. For example, compare the following variants, noticing the stronger pull of version 2 over version 1:
1. There is a gravitational force that pulls on satellites.
2. The Earth's gravitational force pulls on satellites.
Version 2 replaces a generic subject (There) with a specific subject ( The Earth). The weak verb (is) in version 1 disappears in version 2.
HI
34 Words > Verbs
The wise writer keeps there is and there are to a minimum. When editing or revising, rewrite this construction into something more specific.
Vary Your Verbs
Some writers habitually use the same small set of verbs over and over again. To illustrate, consider the following passage:
Figure 1 illustrates the molecular structure of ethyl alcohol, which is an intoxicant. Figure 2 illustrates the molecular structure of methanoate, which smells like raspberries. Figure 3 illustrates the molecular structure of...
The topic is tasty, but the verbs are monotonous. (Each sentence is also plagued by a monotonous grammatical format, but that's a different topic.) Instead of using illustrates three times in a row, try specifies or shows or presents or exemplifies or...
Keep Verbs in the Same Tense
You should maintain the same tense for all verbs within a paragraph. Paragraphs that mix tenses (like the following) sound amateurish:
Hurricanes require high sea-surface temperatures. Another requirement was favorable high-level winds. With light winds aloft, hurricanes will gain power.
The present tense is usually the wisest choice for technical prose. However, the past tense is appropriate for portions of lab reports. After all, lab reports describe what has previously transpired.
You should generally maintain the same tense throughout an entire document. Some editors are extremely insistent on this point. I prefer a more pragmatic approach. For example, consider a book that describes previous research, present research, and potential future research. Clearly, such a book requires multiple tenses.
Words > Verbs 35
Adjectives and Adverbs
Good technical prose ladles in healthy doses of verbs and nouns and generally sprinkles in just an occasional dash of adjectives and adverbs. This is a real pity since adjectives and adverbs can spice a dull dish to life. Unfortunately though, marketing and advertising have made technical people suspicious of adjectives and adverbs. For example, consider the following misguided passage from a hardware manual:
Our video board is extremely fast.
The phrase "extremely fast" smacks of marketing-speak, which raises doubts in engineers' minds. Once the seeds of doubt are planted, engineers will view the remainder of the text skeptically. When you are writing for engineers and scientists, it is much wiser to stick to objective, numerically based facts; for example:
Our video board can render 1.2 million polygons per minute.
The preceding sentence presents an objective fact, which allows the reader to come to his or her own conclusions. Analytical people greatly prefer to come to their own conclusions. Let the mantra "Just the facts, ma'am" echo across your brain as you write.
Before going overboard, note that certain uses of adjectives are just fine. For example, using adjectives to describe physical appearance is essential. The following passage—from a bomb-defusal manual—would be catastrophic without adjectives (red and blue):
Never cut the blue wire; cut the red wire only.
Similarly, occasional adverbs and adverb phrases are also fine, as long as they are objective and specific. For example, the adverb phrase {70%-90% more quickly) in the following sentence will not annoy technical readers:
Adding a second CPU will make our software run 70%-90% more quickly.
36 Words > Adjectives and Adverbs
Pronouns: He, She, and They
The pronouns he and she stir up plenty of trouble. Consider the following variants (all of which are aimed at someone other than the user):
1. When a user enters the password, they are redirected to the home page.
2. When a user enters the password, s/he is redirected to the home page.
3. When a user enters the password, he or she is redirected to the home page.
4. When a user enters the password, she is redirected to the home page.
5. Atter users enter the password, they are redirected to the home page.
6. Atter entering the password, the user is redirected to the home page.
Variant 1 is grammatically incorrect no matter how much we'd all like it to be proper. Unfortunately, in English, you cannot replace a singular user with a plural they.
Variants 2 and 3 are politically and grammatically correct but rather clumsy. In addition, s/he isn't actually a word, and it may confuse nonnative speakers.
Variant 4 is okay, but you must ensure that this particular user (the one entering the password) doesn't morph into he later on.
Version 5 is grammatically correct. After all, the plural users matches the plural pronoun (they). However, the sentence is not completely logical. According to the sentence, users enter the password. Literal-minded readers might imagine that multiple people must enter the same password. Furthermore, according to the sentence, all users will be taken to the home page. Again, literal-minded readers might imagine that all readers will be transported simultaneously to the home page, which is not the intent.
Version 6 is your best bet, basically because it skips right over the entire excruciating gender problem and replaces the pronoun with the androgynous the user.
In some situations, "going plural" (as in version 5) is advantageous, but rewriting sentences to avoid using pronouns (as in version 6) is always safe.
Jul!
Pronouns: You
I love you. You should love you, too.
The second person plural is a valuable pronoun in technical communication. The pronoun you personalizes instruction. It sends a signal to the reader that says, I care for you. In addition, using the pronoun you improves an audience's attention. (Yeah, I'm talkin' to you.) For example, compare the following variants:
1. When the centrifuge starts, the operator may hear a brief cranking sound.
2. When the centrifuge starts, you may hear a brief cranking sound.
Doesn't version 2 sound more personal and friendly than version 1? In real life, wouldn't you prefer that someone refer to you as you rather than as the operator 7 . Naturally, the writer must first be certain that you (the reader) really are the operator.
Imperative verbs are commands. Imperative verbs act as an implied you. Do not place you in front of an imperative verb. (In fact, when you place a pronoun in front of an imperative, the verb is no longer imperative.) For example, although the following two variants are synonymous, version 1 sounds more natural:
1. Start the centrifuge.
2. You start the centrifuge.
38 Words > Pronouns: You
If used infrequently, the pronouns it and they are benign. However, many readers mistakenly use these pronouns with abandon. It becomes the favorite subject for lazy passages, used instead of a more specific noun. For example, notice how many times the following passage contains it:
The carambola is a delicious fruit. It is native to Malaysia, but it now grows in various other places, as well. It is very sensitive to cold weather. It is often called "star fruit."
The following passage reduces occurrences of it:
The carambola is a delicious fruit. Although native to Malaysia, this fruit now grows in various other places as well. The tree is very sensitive to cold weather. It is often called "star fruit."
If you look carefully at the two passages, you might spot another problem with it, which is that writers sometimes change the meaning of if within a paragraph. In the first passage, note that it refers to a fruit. However, a few sentences later, it has become a tree. In the second passage, notice that the tree—not the fruit—is very sensitive.
See if you can detect the transgression in the following passage:
Oranges are higher in Vitamin C than avocados, but they have more protein.
Which has more Vitamin C: oranges or avocados? Readers cannot tell. A lazy writer has introduced two nouns and then mapped only one (and we cannot determine which one) to they. You must always be perfectly clear what they refers to.
Words > Pronouns: It and They 39
Fluffy Phrases
One of the oldest cliches in writing is to avoid old cliches when writing. Unfortunately, due to habit, most educated people rely on stock, fluffy phrases when a single word will do. These phrases are so ingrained in your writing that you can probably no longer recognize them as fluffy. For example, in the following variants, notice that version 2 is more concise and clearer than version 1:
1. Failure to destroy Object Q will cause the introduction of memory leaks.
2. Failure to destroy Object Q will introduce memory leaks.
Version 2 eliminates three words from version 1.
Table 4-1 identifies a few common wasteful phrases. Once you start noticing these wasteful phrases, many more will pop at you.
TABLE 4-1 Replace Wasteful Phrases with Their Frugal Equivalents
In some sentences, you can simply remove the wasteful phrase that is to say altogether rather than replacing it with that is.
40 Words > Fluffy Phrases
Commonly Confused Words
This section describes the words most commonly confused in technical prose.
That and Which
Even professional writers often have trouble using the words that and which correctly, so pay careful attention to that which I'm about to say. The paradox is that although the two words are synonyms, you may not use them interchangably. Without getting into excruciating grammatical terms, the rule of thumb is as follows:
• Use which immediately after a comma.
• Do not use that immediately after a comma. Compare the following sentences:
• Maple trees produce a sweet sap that farmers process into syrup.
• Maple trees produce a sweet sap, which farmers process into syrup.
Can and May
Writers chronically interchange can and may. Table 4-2 highlights the difference.
TABLE 4-2 Can versus May
Word Meaning Example
Can Is able to This computer can execute 20 billion instructions per second.
(This computer is able to execute 20 billion instructions per second.)
May Has permission to If you have write permission on the directory, you may create a or is allowed to file in it. (If you have write permission on the directory, you are
allowed to create a file in it.)
The word may also indicates "a possibility of." For example, in casual speech, the meaning of the following sentence is perfectly clear:
It may ram.
Words > Commonly Confused Words 41
In formal technical prose, you should avoid using may to indicate possibility as it leads to confusion with the other common meaning of may. Within formal technical prose, it is wiser to use "possibility" or "probability" instead of may, as in the following example:
The Weather Service forecasts a 50% probability of rain.
Effect versus Affect
Effect and affect are similar-sounding, common technical words whose meanings change depending on whether the words are being used as a noun or as a verb. Cutting to the chase, Tables 4-3 and 4-4 highlight their most common uses in technical and scientific writing.
Its and It's
If the English language were an engineering project, I'd submit a high-priority change request to create a substitute word for its. Unlike every other possessive in English, its does not contain an apostrophe. Table 4-5 differentiates between its and it's.
I
42 Words > Commonly Confused Words
Summary of Words
When reviewing your word choices, ask yourself the following questions:
• Are these words appropriate for the target audience? Does the target audience know what these words mean? Are any words too "big" for their own good?
• Does this document contain jargon? Does your target audience know the definition of this jargon? If your target audience is a lay audience, do you provide definitions?
• Are all the words clear? Can you replace a word with a more specific or accurate word?
• Are the verbs strong or generic? Can you rewrite sentences containing there is or there are'.
• Are all the verbs in the same tense? In general, they should be.
• Does the same verb appear repeatedly? Vary your verbs.
• Are any words unnecessary? Can you reduce or remove certain words?
• Are any adjectives or adverbs unnecessary? When writing a technical document for a technical audience, you should remove most adjectives or adverbs that suggest marketing pressure.
• Are the pronouns grammatically correct? For example, do any sentences refer to one person as they 7 .
• Does the document overuse it 7 . Are any uses of it or they ambiguous? In other words, does the reader always know which noun it or they refers to?
• Does the document refer to the reader as you 7 . It should.
• Does the document apply each word correctly? If in doubt, refer to a dictionary or style guide. Fay particular attention to that and which, can and may, and affect and effect.
Words > Summary of Words 43
CHAPTER 5
Sentences
A run-on is the kind of sentence that just keeps rolling along until the furthest shores of infinity, churning and churning without really saying anything, reiterating what has come before and not really advancing the point until the reader is bored and moves on to the next book—any book (even an art history book)—on the shelf at the bookstore. Yep, that's a run-on sentence. That is the kind of sentence that you are not going to write. That's because you, my friend, are an engineer or scientist, and people with logical minds hate fluff. You adore signal and despise noise.
Sentences don't have to be long to be noisy; sentences can be as short as Napoleon but still be noisy if they don't say anything valuable. Similarly, sentences can be filled with good data that gets lost in a confusing structure.
Writers generally cannot detect noise in their own prose. After all, noisy writing emits no sound or spark (unless you count the grinding of a frustrated reader's teeth). Fortunately, a good editor can detect noise in your sentences and help you filter it out. Like any engineering process, writing effective sentences must endure critical analysis and iteration.
This chapter takes you through the key components of writing good sentences, which include the following:
• using active voice
• keeping sentences short
• aiming for clarity above all
111
Sentences 45
Active Voice and Passive Voice
In an active-voice sentence, the subject acts on the object. For example, the sentence in Figure 5-1 is in active voice because alpha particles (the subject) act on the nucleus (the object).
Alpha particles strike the nucleus.
~~r "T
Subject Object
FIGURE 5-1 Active-Voice Sentence
In a passive-voice sentence, the subject is acted upon by the object. In most passive-voice sentences, the object appears at the beginning and the subject appears at the end. For example, the sentence in Figure 5-2 is in passive voice because alpha particles (the subject) are acted upon by the nucleus (the object).
i
The nucleus is struck by alpha particles.
Object Subject
FIGURE 5-2 Passive voice sentence
Table 5-1 provides a few more examples.The final passive voice example omits a subject altogether. (Who measured barometric pressure? It is hard to say.)
TABLE 5-1 Examples of Active Voice and Passive Voice Passive Voice Active Voice
GIFs are displayed by the browser. The browser displays GIFs.
Two parties are connected by telephones. Telephones connect two parties.
Barometric pressure was measured. The team measured barometric pressure.
46 Sentences > Active Voice and Passive Voice
Active Voice Is Better
Active-voice sentences offer the following compelling advantages over passive-voice sentences:
• Active-voice sentences are usually a little shorter than their passive-voice equivalents.
• Most readers find active voice clearer and more natural than passive voice.
• Active-voice sentences are more powerful and energetic than passive-voice sentences.
• Readers for whom English is a second language will find active voice easier to understand than passive voice. (Students of English as a second language invariably learn active voice long before they learn the passive voice.)
In summary, active-voice sentences are generally superior to passive-voice ones.
Well... How Did I Get Here?
The urge to write passive-voice sentences is often the by-product of a good education. Advanced academic writing is often riddled with passive voice. Passive voice generates an effete air, while active voice just sounds so plebeian. Class connotations aside, clarity is the shining gold standard of technical communications, and clarity requires active voice.
The worst misuse of passive voice is the sentence that omits a subject altogether. In technical and scientific writing, it is critical that the reader understand who is doing what to whom. By tradition, scientists often skip subjects in lab reports. According to this tradition, the absence of subjects makes lab procedures sound less subjective and more factual. Thus, temperatures are taken and slides are viewed. However, outside of Harry Potter, microscopes do not see; humans see through microscopes. It is high time to acknowledge the actor in each action. The following list provides a few convenient actors for lab reports:
• the authors
• the study
• the lab team
When Is Passive Voice Okay?
Using passive voice once in a while is okay. For example, you might prefer to use passive voice when you want to stress the object rather than the subject. For example, consider the following active-voice sentence:
Hurricanes seldom hit New York City.
The preceding active-voice sentence is dandy if the topic is hurricanes. However, if the topic-is New York City, then a passive-voice sentence such as the following might make more sense:
New York City is seldom hit by hurricanes.
Sometimes you use passive voice to obscure the subject intentionally, perhaps to spare blame. For example, consider the following two politically expedient, passive-voice sentences:
Mistakes were made.
Hmm, the last autoclave has been taken.
You may sprinkle in an occasional passive-voice sentence for the sake of variety to break up the monotony of a string of active-voice sentences. (We'll revisit sentence variety in the next chapter.)
II
48 Sentences > When Is Passive Voice Okay":
Short = Sweet
Long story short—readers prefer skinny sentences to fat ones. This is a tough lesson to learn because, as you got older, your teachers rewarded you for writing longer sentences. In fact, your ability to write bloated sentences was an indicator that you were "educated." Good engineers do not simply invent clever devices. Rather, they invent devices that can be manufactured as cheaply as possible. Your goal as a writer is similar—you must convey information in a minimum of words.
Long sentences are evil for the following reasons:
• They are visually intimidating.
• They are harder to understand than short ones.
• They often obscure the writer's intent.
In Table 5-2, note the relative clarity of the shorter version.
TABLE 5-2 The Long and Short of It
Long Version
Short Version
The efficiency of Web browsers in displaying graphic images is in direct correlation to the disk resources required by the aforementioned graphic images.
Web browsers display small graphics files more quickly than big graphics files.
It would be extremely tedious, and in most cases irrelevant, for us to concern ourselves with the atomic or molecular structure of macroscopic ob|ects whose gravitational attraction is to be studied when the object's mass is essential.
Gravitational force depends on an object's mass, not on its chemical structure.
Liquid precipitation on the western Iberian peninsula is primarily deposited on flat, non-mountainous regions.
The rain in Spain falls mainly on the plain.
Keeping It Bite-Size
At Chinese restaurants, the chef chops food; patrons do not. This is why you will rarely find knives on the table at Chinese restaurants. As a writer, you must become the Chinese chef—chopping your sentences into delectable morsels so that your readers do not have to work so hard.
Causes of Long Sentences
I've rounded up the usual suspects for killing your readers' time:
• jamming two or three ideas into a single sentence
• using passive voice
• being repetitious
• being repetitious
• being repetitious
• using words or phrases that do not pull their weight
• embedding lists that should be broken into bulleted or numbered lists
When is a sentence too long? It is difficult to come up with a magic formula. A 12-word sentence that minces words might be too long, while a crystal clear 20-word sentence is sometimes just perfect. In general, though, you should rarely go beyond 25 words and almost never beyond 30 words.
Readability Formulas
Plugging prose into a readability formula generates a readability quotient. Most readability quotients are pegged to an educational level. Thus, a certain readability formula might indicate that a particular book is appropriate for eighth graders. Quite a few readability formulas are currently in use. Most rely on some mix of the following parameters:
• average number of words per sentence
• average number of "hard" words per sentence
• average number of characters or syllables per word
Unfortunately, many writers take readability quotients far too seriously, forgetting that these formulas omit common sense. For example, Ernest Hemingway wrote beautifully short sentences comprising short, simple words. Plugging some of his novels about bullfighting, combat, and sexual dysfunction through certain readability formulas yields books with a readability quotient suitable for fifth graders.
When writing technical prose for adult professionals, do not intentionally aim for a college-level readability quotient. Aim to make your message clear. Shoot for the best possible signahnoise ratio.
II
50 Sentences > Causes of Long Sentences
One Sentence = One Thought
A sentence should represent a single thought or idea. When a sentence holds multiple thoughts, you should pick one of the following tactics:
• Divide the sentence into multiple sentences.
• Divide the sentence into two parts connected by a semicolon. Consider the following heavy sentence, pregnant with multiple ideas:
Our sun is a yellow dwarf star, which is powered by nuclear fusion in a process that should last for a few billion more years or about as long as the balance is maintained between readily fusionable material and gravity, at which time it will transition to another star category.
The preceding sentence is a classic 50-word run-on, slogging along in a marathon when a series of short sprints would have worked better. The sentence contains four discrete thoughts (category, power source, duration, transition), so consider the following replacement containing four sentences:
Our sun is a yellow dwarf star. Fusion powers all yellow dwarves. Our sun has enough fuel to last a few billion more years. When gravity can no longer keep atoms close enough to fuse, our sun will transition to another star category.
The resulting series of sentences is an improvement; however, it is rather choppy. To eliminate some of the choppiness, you might rewrite the opening as follows:
Our sun is a yellow dwarf star, which is powered by fusion.
However, I'm not wild about this solution because this single sentence contains two discrete thoughts (category and power source). In addition, putting the power source after the comma relegates it to a second-class factoid. To work around these problems, connect the two thoughts with a semicolon instead of a comma, as in the following example:
Our sun is a yellow dwarf star; fusion powers all yellow dwarves. Notice that the power source is now on an equal footing with the category.
Sentences > One Sentence = One Thought 51
Parenthetical Clauses
A parenthetical clause is a digression, example, or elaboration within a sentence that is bounded by a pair of any of the following punctuation marks:
• commas
• parentheses
• dashes
For example, the following parenthetical clause is a digression bounded by a pair of dashes: Carbon—an element in all amino acids—can easily bond with hydrogen
If you eliminate a parenthetical clause, the resulting sentence must still make sense. For example, eliminating the preceding parenthetical clause leaves the following simple sentence:
Carbon can easily bond with hydrogen.
The fiction writer Henry James loved parenthetical clauses and wrote enormous sentences, each of which would take well-educated Victorians an entire evening to read. Unfortunately, today's technical reader is not quite as patient. In technical prose, occasional parenthetical clauses are fine, but don't overuse them. No sentence in technical prose should contain more than one parenthetical clause.
In many programming languages, it is fine to place a pair of parentheses inside another pair of parentheses. However, you should avoid this practice in technical prose. Humans are less comfortable with recursive parsing than compilers.
Of course, commas and dashes can mark more than just parenthetical clauses. Both can also denote simple pauses. Since frequent pausing doesn't appeal to technical readers, you should not overuse commas and dashes.
52 Sentences > Parenthetical Clauses
Summary of Sentences
When reviewing your writing, ask yourself the following questions about each sentence:
• Is this sentence clear? Will the target reader understand it? Is this sentence too complex for the target reader, or does it require knowledge that the target reader does not possess? Conversely, does this sentence insult the target reader's intelligence? All other items in this checklist are subservient to clarity; make clarity your primary goal.
• Is this sentence really a sentence? (All sentences must contain a verb.)
• Is the verb strong and specific, or is it weak and generic? The verb is generally the most important word in the sentence—choose a powerful one.
• Does this sentence contain an embedded list? If so, you should typically break it out to form a bulleted or numbered list.
• Is this sentence in passive voice? Most sentences should be in active voice.
• How many ideas does this sentence convey? Each sentence should convey exactly one idea, although you can connect two closely related ideas with a semicolon.
• Is this sentence a run-on? Does it go yackety-yack and waste your time of day? If so, find a way to reduce its length, possibly by dividing it into two or more sentences.
• Is this sentence—while not a run-on—still longer than it needs to be? Always search for fat to trim.
• Does this sentence contain too many parenthetical clauses? Occasional parenthetical clauses are okay, but when overused they become literary speed bumps.
• Do you need this sentence at all? If you deleted this sentence, would the reader miss it? If the reader would not, erase it. After all, the reader will never know what you removed.
■Ill Sentences > Summary of Sentences 53
CHAPTER 6
Paragraphs and Sections
omewhere in your schooling, a good English teacher probably taught you how to write good paragraphs. The key, the teacher said, was starting with a solid topic sentence that introduced the paragraph and provided its theme. The essays you wrote in high school contained long paragraphs, which really did benefit from topic sentences.
Technical writing differs from the literary essays you wrote in high school. Technical prose simply cannot afford a topic sentence for every paragraph. The paragraphs in technical prose are more utilitarian, less rigidly structured, and generally shorter than in literary criticism. In technical prose, two-sentence paragraphs are common. In such short paragraphs, a topic sentence is hardly warranted. The opening sentence in a technical paragraph does not need to state a theme; it merely needs to introduce the topic at hand or to build on the topic that preceded it.
A section is a collection of one or more paragraphs (plus any lists, tables, or figures). A section that consists of several paragraphs does require an introductory paragraph. This introductory paragraph should start with one of the following:
• a topic sentence
• a bulleted or numbered list of topics covered in this section
This chapter details the special requirements for paragraphs in technical prose.
Paragraphs and Sections 55
Sentence Transitions
A transition is a word or phrase that helps ease readers into the next sentence. The following is a list of common transition terms in technical prose:
• however
• for example
• nevertheless
• by contrast
• by comparison
• in other words
• unfortunately
• that is (but don't use this one too often)
Transitions terms typically appear at the beginning of a sentence. For example, consider the following use of a transition term in the second sentence:
Transitions terms typically appear at the beginning of a sentence. For example, consider the use of a transition term in this sentence.
When a sentence twists abruptly from the previous sentence, a transition term acts much like a squiggly road sign warning readers of a quick turn up ahead. For example, in the following passage, consider the sharp turn the second sentence makes from the first:
Newton's formulas work remarkably well. These formulas fail miserably when objects are very small or are moving very rapidly.
Adding a transition term supplies a warning to the reader, so the following passage reads more easily:
Newton's formulas work remarkably well. However, these formulas fail miserably when objects are very small or are moving very rapidly.
The wise writer pays attention to transitions. Without transitions, paragraphs often sound static and forced. With well-chosen transitions, writing sounds more natural and conversational. Ironically, speakers in actual conversations do not use many transition words.
II,
56 Paragraphs and Sections > Sentence Transitions
Vocal inflections, facial expressions, and hand gestures act as transitions in real-life conversations.
In Table 6-1, notice how much more fluid the passages with transitions sound.
TABLE 6-1 The Value of Transitions
Without Transitions
With Transitions
The C compiler can process 1,000 lines of code per second. The rate slows when the host is fully loaded.
The C compiler can process 1,000 lines of code per second. However, the rate slows when the host is fully loaded.
Most commercial airplanes can cruise at altitudes up to approximately seven miles. The Boeing 757 cruises at 37,000 feet.
Most commercial airplanes can cruise at altitudes up to approximately seven miles For example, the Boeing 757 cruises at 37,000 feet.
The only downside to using transitions is that they make sentences a little longer. Nevertheless, transitions aid clarity and help engage the audience.
Conjunctions Are Not True Transitions
It is tempting to start a sentence with But or And. But don't do it in technical writing. And here's why— but and and are conjunctions, great for intrasentence transitions but not appropriate for intersentence transitions.
Note that starting a sentence with a conjunction is fine in fiction. The rules of fiction are not as rigid as those for technical prose. Furthermore, in real-world conversations (which is something that fiction writers try to emulate), speakers start sentences with conjunctions all the time.
Although transitions are wonderful, don't feel obligated to force them into every sentence. Moderation is also powerful.
Paragraph Length
In high school English class, you may have been taught to write paragraphs to the following formula:
• The first (or topic) sentence introduces the paragraph.
• The middle three sentences are the body of the paragraph.
• The final sentence summarizes the paragraph.
Consequently, every paragraph consumed roughly five sentences.
When writing technical prose as an adult, you might have brought along that same rigid formula (one paragraph ~ five sentences). Allow me to liberate you—a paragraph should be as long or short as is needed. Some paragraphs should weigh a skimpy two or three sentences, while others should weigh a robust seven or eight sentences. Both weights are equally healthy.
Many good writers vary the length of paragraphs. Changing the length keeps readers awake. Some writers intentionally pop in an occasional lengthy paragraph after a quick series of short paragraphs. Your high school English teacher might not approve, but your readers will.
Yes, an occasional one-sentence paragraph is fine.
Beware of the rambling, massive paragraph that just never ends. When editing such a paragraph, I sense that the writer hasn't figured out the right key to press to trigger a new paragraph. A one-ton paragraph possesses an intimidating amount of girth and heft. Reading such paragraphs is a chore, which is why many readers simply skip over them. The obvious solution is to divide morbidly obese paragraphs into multiple svelte, healthy ones.
When writing for a medium (such as newspapers) that contains very narrow columns, your paragraphs must be exceedingly short, oftentimes only a sentence or two.
58 Paragraphs and Sections > Paragraph Length
Paragraph Transitions
The opening sentence of a paragraph should flow fairly naturally from the preceding paragraph. For example, in the following passage, notice that the opening sentence of the second paragraph transitions by tightly summarizing earlier facts before segueing to the next topic:
Dolphins are outstanding swimmers that can move at up to 30 miles per hour. Some dolphin species can hold their breath for up to ten minutes. Eventually though, dolphins must come up for fresh air since they have lungs, not gills.
Although dolphins both breathe air and swim expertly, dolphins are not amphibians. True amphibians start their life in water prior to transitioning...
Many editors frown on starting a paragraph with a transition term, feeling that transition terms connect sentences, not paragraphs. For example, some editors would forbid the following paragraph opening:
However, dolphins are not amphibians.
If you cannot make a paragraph flow naturally from its predecessor, then place that paragraph in a new or different section.
Paragraphs and Sections > Paragraph Transitions 59
Sections
You should divide any document longer than a page or two into distinct sections. Doing so makes the document easier to write and easier to read. Each section must begin with a section header, which is its title. The following are some guidelines for sections and section headers:
• The opening sentence of a section should establish the section's purpose.
• Each section must contain at least one sentence. That is, you may not place two sections in a row without intervening text.
• Section names should be grammatically parallel. For details on parallelism, see "Parallel Lists" on page 70.
• Section names are not body text and should not be treated as such. For example, a section header cannot act as a valid introduction to a list; you must supply the introductory sentence in body text.
• Section levels should rarely go more than three levels deep, counting the title of the document (or the chapter title) as the top level. In other words, beyond that top-level header, you should only supply two additional levels of headers. At the fourth level, many readers lose track of the hierarchy, which leads to confusion.
Should You Number Section Headers?
Many documents provide a multilevel section number in front of each section name, as in the following section header:
3.6.4 Orcas Make Poor Pets
You should place section numbers on the following types of documents:
• Engineering documents that serve a legal purpose. For example, documents that are attachments to a contract almost always contain section numbers. Section numbers reduce ambiguity when lawyers discuss the contract.
• Engineering documents in which section numbers are a contractual requirement. For example, most military organizations require documents to contain section numbers.
When writing for a lay audience, avoid section numbers. To members of a lay audience, section numbers appear formal and intimidating, rather like a big red "nerd crossing ahead" warning flag being waved in their faces.
60 Paragraphs and Sections > Sections
Summary of Paragraphs and Sections
When reviewing your writing, ask yourself the following questions about each paragraph:
• Does each sentence flow naturally into the sentence that follows?
• Do sentences sound choppy? If so, consider adding transition terms to the beginning of choppy sentences.
• Do any sentences start with conjunctions instead of proper transition terms?
• Does each paragraph flow naturally into the paragraph that follows?
• Do any paragraphs start with transition terms? They usually should not.
• Are any paragraphs too long? Be wary of paragraphs longer than eight sentences or so. Chop lengthy paragraphs into two or three shorter ones.
• Do all the sentences in a paragraph belong together, or do some sentences veer so far off course that they belong in another paragraph?
When reviewing your writing, ask yourself the following questions about each section:
• Is each section header descriptive? In other words, does each section actually describe what the section header says it should?
• Can any section headers be more specific? For example, calling a section header "Orcas" might not be not nearly as informative to readers as calling it "Orcas: Diet."
• Are all the paragraphs in a section related, or do some paragraphs belong in a new or different section?
Paragraphs and Sections > Summary of Paragraphs and Sections 61
CHAPTER 7
Lists
r
n offbeat publication from the 1970s, The Book of Lists by David Wallechinsky and Amy Wallace, was literally just a bunch of lists. However, readers loved it and made it into a best-seller. What could account for this book's popularity? Perhaps it was the titillating list categories, such as the top ten sex positions or ten worst dictators. Alternatively, perhaps readers just get a big kick out of lists. After all, lists neaten and straighten a ragged world. Lists condense information and force readers to focus. Even the layout of lists is favorable, making their information hard to ignore.
This chapter explores the following two kinds of lists:
• bulleted lists, which present unordered information
• numbered lists, which present ordered information
Inexperienced writers often confuse the two kinds of lists and pick the wrong one. Fortunately, the following rule of thumb will allow you to pick correctly:
If rearranging the elements in a list would not alter the list's meaning, then the list should be bulleted. If rearranging the elements in a list would cause the list to become confusing or incorrect, then this should be a numbered list.
Bulleted Lists
A bulleted list is the smart alternative to an embedded list. For example, the following sentence contains an embedded list:
A tropical cyclone consists ot a large area of low pressure, a closed isobar, sustained winds greater than 25 knots, consistent thunderstorms around the center, and a warm core.
Elements within an embedded list tend to hide. Transforming an embedded list into a bulleted list provides far more clarity:
A tropical cyclone consists of the following:
• a large area of low pressure
• a closed isobar
• sustained winds greater than 25 knots
• consistent thunderstorms around the center
• a warm core
Readers enjoy bulleted lists, so use them liberally. Do not, however, overuse them—too many bulleted lists will transform your prose into a PowerPoint presentation.
Preface each item in a bulleted list with a bullet. A bullet is traditionally the following filled circle punctuation mark:
However, you could use another mark for the bullet as long as you do so consistently across the document.
How Many Elements Comprise a Bulleted List?
What is the minimum number of elements one can put in a bulleted list? Some writers say two elements and some say three. I feel that two elements is the usual limit. However, you may create a one-item bulleted list in documents that have conditioned readers to expect certain kinds of information in bulleted lists. For example, suppose each page of a document starts with a bulleted list enumerating achievements in pharmacology for a given year. If 1971 produced only one significant achievement, then the 1971 page should still begin with a one-element list.
1
64 Lists > Bulleted Lists
Elements in Bulleted Lists
The text for each element in a bulleted list can be just about anything, as long as each element is grammatically consistent. (For more on consistency, see "Parallel Lists" on page 70.) In the following example, each element of the list is a singular noun:
The following are simple trigonometric functions:
• sine
• cosine
• tangent
List elements may also be sentence fragments (as in the first example on the preceding page) or complete sentences, as in the following example:
The strength of the two primary physical forces depends on the following:
• Gravitational force is proportional to the mass of the two objects.
• Electrical force is proportional to the charge on the two objects.
Each element of a bulleted list can itself contain a sublist. Each element of a sublist must also start with a bullet. The bullet for the sublist must be indented further than the bullet for the main list. A main list and sublist provides an effective means for creating a hierarchy. A sublist can also provide details about entries in the main list; for example:
The genus Canis includes the following members:
• Wolves:
- Weight is between 20 and 80 Kg.
- Tail is often horizontal.
• Coyotes:
- Weight is usually less than 20 Kg.
- Tail is usually down.
The Length of Each Element
Keep list elements short. In general, do not let list elements exceed three sentences. If you are producing lists for a medium with very narrow columns (such as a newspaper), then you should keep list elements down to a single sentence.
When list elements get too long, consider dividing them into two or more separate elements or possibly into a new section of your document, complete with subheads. For example, consider a bulleted list having the following structure:
Intro:
• Sentence 1. Sentence 2. Sentence 3. Sentence 4. Sentence 5.
• Sentence 6. Sentence 7. Sentence 8. Sentence 9. Sentence 10. Sentence 11.
• Sentence 12. Sentence 13. Sentence 14. Sentence 15.
The elements in the preceding list are too long to be effective as a bulleted list. Convert the preceding into a short bulleted list and three subheads as follows:
Intro:
• Sentence 1.
• Sentence 6.
• Sentence 12.
Subhead
Sentence 1 altered. Sentence 2. Sentence 3. Sentence 4. Sentence 5.
Subhead
Sentence 6 altered. Sentence 7. Sentence 8. Sentence 9. Sentence 10. Sentence 11.
Subhead
Sentence 12 altered. Sentence 13. Sentence 14. Sentence 15.
1
66 Lists > The Length of Each Element
Numbered Lists
Numbered lists describe events that must happen in a certain order. Use numbered lists to describe a sequence of steps. For example, consider the following numbered list:
Perform the following steps to begin driving:
1. Turn on the ignition.
2. Release the emergency brake.
3. Put the car in drive.
4. Press the accelerator gently.
Changing the order of the elements in the preceding list would lead to car repairs. Therefore, the preceding list must be numbered; it cannot be bulleted.
^QUANTUM LEAP:
In the preceding list, what do the first words (Turn, Release, Put, Press) in each sentence have in common? Each of these words is an imperative verb, meaning that it is a command for the reader to follow. It is a great idea to start each element of a numbered list with an imperative verb. The imperative will keep your sentences short and crisp.
Each element in a numbered list should describe one and only one action. For example, consider the following alteration:
Perform the following steps to begin driving:
1. Turn on the ignition and release the emergency brake.
2. Put the car in drive and press the accelerator gently.
At first glance, the preceding list looks pretty good. However, readers are more likely to miss details in the two-step list than in the four-step list. The wise writer does not place multiple actions in a single numbered step.
Do not start a numbered list element with the word then. The number prefacing each list element is an implied then.
Directions
Numbered lists provide the best medium for giving directions. For example, consider the following directions:
To travel from my house to the college, follow these steps:
1. Travel 2.4 miles west on Occidental Blvd.
2. Turn right on Nordic Ave.
3. Travel 1.2 miles on Nordic Ave.
4. Turn left on Waverley Blvd.
5. Travel 0.6 miles.
6. Turn right into "Parking Lot C" and find a parking spot.
Avoid obfuscating your directions with too many extraneous details, such as "if you see Harry's Discount Law and Garden, you've gone too far." Nevertheless, consider providing a few helpful details to work through difficult patches; for example, the following revision to step 4 provides some useful troubleshooting information:
4. Turn left on Waverley Blvd. The street sign is missing, so look for Puddingstone Bank on the corner of Waverley.
Avoid ordinal numbers in directions. Do not, for example, say that Waverley Blvd. is at the third traffic light. Ordinal numbers produce a surprising amount of confusion. (When should we have started counting traffic lights? Did the flashing yellow light at the crosswalk count as a traffic light?) Ordinal numbers also make troubleshooting difficult.
Know your audience. Are your readers mathematically inclined and content to deal with mileage figures and odometers? Are your readers more word oriented, preferring textual descriptions of hills and pretty red houses on the corner?
As you write a numbered list, imagine that readers are checking off each step as they complete it. Keep each entry discrete.
As you'll see later on, these same principles will also apply when you are providing instructions for scientific procedures.
Introductions to Lists
You may not just blurt out lists; you must introduce them properly. Introductions are more than grammatical etiquette; they are essential for meaning.
• carambolas
• milk chocolate
• corn chips
Whoa—did you see how I just blurted out the preceding list? What did those items mean? Since I didn't introduce the list properly, you probably have no idea. I didn't supply enough context to help you comprehend the list. 1
When introducing a list, try to work the word following into the sentence. For example, consider the following beautiful introductory sentence:
The following is a list of deciduous hardwoods:
• oak
• maple
Alternatively, consider the following variants on the preceding introduction:
Deciduous hardwoods include the following examples: Examples of deciduous hardwoods include the following:
By putting/o/fowng in an introductory sentence, you are likely to produce a useful context for the list. Don't try to understand this magic—just accept it.
Look Out Below
Never use the word below when introducing a list. Lists have a nasty habit of sliding to the next physical page. Thus, the list might not really be spatially below the sentence that introduces it. Using the word following instead of below keeps you safe, even if the list moves to the top of the next page. For the same reason, avoid the word above when referring to a previous list. Use the word preceding instead.
1. These are my favorite snack foods.
Parallel Lists
Each element in a list must have the same grammatical form. For example, if the first element in a list is a singular noun, then all elements must be singular nouns. If the first element is a complete sentence, then all elements must be complete sentences. If the first element in a list starts with an imperative verb, then all elements must start with a imperative verb. In addition, punctuation and case must be consistent for all elements in a list.
A list in which each element is consistent is said to be parallel, and a list of inconsistent elements is called nonparallel. Creating parallel lists does not come naturally to most writers—it requires a fair amount of discipline and a frustrating amount of rephrasing. Nevertheless, one of the surest ways to produce an amateurish document is to pepper it with nonparallel lists.
Beyond simple grammar, each element in a parallel list must logically belong to that list.
On this page and the next, we will consider a few parallel and nonparallel lists. See if you can determine which lists are nonparallel and why. (Note that the answers follow the sample lists.) We begin with the following list:
• lemon
• lime
• orange
The preceding list is beautifully parallel. All the elements are singular nouns.
• lemons
• lime
• orange
The preceding list is nonparallel because the first element is plural, while the other two elements are singular.
• lemon
• lime
• orange
70 Lists > Parallel Lists
The preceding list is nonparallel because, unlike the first two elements, orange did not start with an uppercase letter.
• lemon
• lime
• orange tree
At a grammatical level, the preceding list is okay; however, this is a nonparallel list because the third entry just does not logically belong with the other two.
1. Insert the CD.
2. Invoke setup.exe.
3. Answer the prompts.
The preceding list is parallel. All three elements are simple verb phrases. Each of the phrases starts with an imperative verb. All end with a period (as they should).
1. Insert the CD.
2. Invoke setup.exe.
3. Answer the prompts.
The preceding list is nonparallel. Notice that the first two elements end in a period, but the third element does not. To create a parallel list, you must use punctuation consistently. By the way, most writers place a period at the end of list elements that are verb phrases or complete sentences, and they omit the period from list elements that do not contain a verb.
1. Insert the CD.
2. Invoke setup.exe.
3. You must answer the prompts.
The preceding list is nonparallel because, unlike the first two elements, the third element starts with a pronoun.
Capitals and Periods in List Elements
Punctuate each element of a numbered list as you would a sentence; that is, capitalize the first letter of the opening word and end the element with a period. For a bulleted list, if the list elements are sentences or verb phrases, supply sentence punctuation. Otherwise, do not supply sentence punctuation.
Ill
Summary of Lists
When reviewing your writing, ask yourself the following questions about each list:
• Should this list be bulleted or numbered?
• Does my text contain any embedded lists? Should these embedded lists be broken out into bulleted or numbered lists?
• Should any complex list elements be converted into sublists?
• In a numbered list, do my elements begin with an imperative verb? (Numbered lists frequently begin with an imperative, but they don't have to.)
• Is the first element in a numbered list labeled as number 1?
• Is each list properly introduced? Does the introductory sentence end with a colon? Does any text refer to list below or above instead of using the proper words following or preceding?
• Are all list elements parallel?
1
72 Lists > Summary of Lists
CHAPTER 8
Tables
Tables are a terrific organizational tool for communicating certain kinds of data. They provide a pleasant visual break from page after page of prose. They divide an untidy world into nice neat fields, appealing to the obsessive-compulsive in us all. When organized appropriately, they act as an outstanding reference medium, allowing readers to quickly find what they seek.
Technical readers generally adore tables. Most lay readers appreciate simple, well-organized tables but often shy away from complex tables containing too many columns. Many technophobes are afraid of tables simply because they look rather technical.
Good tables have the following characteristics:
• They begin with a good caption that summarizes the contents of the table.
• Every column contains a clear, accurate header.
• The contents within each column are grammatically parallel.
• They are organized so that readers can easily find what they seek. Bad tables often exhibit the following two problems:
• The contents of cells are so concise that they become cryptic.
• The contents of cells are so long-winded that the concise value of tables is lost.
■ Tables 73
Column Headers
You should provide headers for every column in almost every table. Good headers make data much easier to understand. However, writers often omit column headers, believing that the contents of each column are so obvious that headers are a waste of space. In fact, bad or missing headers can lead to ambiguity and miscommunication. For example, consider Table 8-1, which contains no column headers.
TABLE 8-1 Members of the Willow Family (without headers)
Although the contents of the leftmost column of Table 8-1 seem fairly obvious, the values in the other two columns could have several possible meanings. Table 8-2 provides column headers, which clarify matters considerably.
TABLE 8-2 Members of the Willow Family (with headers)
When naming columns, be as specific as possible, even if the resulting name is not concise. For example, in the previous table, although Continent is more concise, Continent of Origin is far less ambiguous.
74
Tables > Column Headers
Units of Measure
As someone with scientific training, you know how important it is to specify accurate units of measurement. Technical writers specify table units in one of the following three places:
• in each cell
• in table footnotes
• in column headers
Specifying the unit in each cell provides unambiguous data. However, it also generates redundant clutter, as in Table 8-3.
Providing footnotes reduces clutter but also reduces clarity; readers must move their eyes to multiple spots to get the full story. When viewing Table 8-4, notice how many turns your eyes must take to locate the trunk diameter of a black walnut.
a. In feet
b. In inches
Specifying units in column headers, as in Table 8-5, is usually the best approach. TABLE 8-5 Specifying Units In Each Column Header
Referring to Tables
In text, refer to a table as the following table, the preceding table, or as a specific table number (Table 8-12). Don't refer to the table by its caption (the Mulberry table).
1
76 Tables > Units of Measure
Arrangement of Columns and Rows
For each table, you must pick one column to be the central organizing unit. Place this primary column in the leftmost position in the table, primarily because English readers are accustomed to starting from the left and moving to the right.
Compare Tables 8-6 and 8-7.
TABLE 8-6 North American Tree Families
Choose Table 8-6 when readers are more familiar with tree families and Table 8-7 when readers are more likely to look up entries by species.
Tables in Documents Are Not Tables in Relational Databases
Tables in documents are not subject to the same rules as tables in relational databases. For example, each table in a relational database must define one column to be the primary key. The value of a primary key must be unique. In other words, two rows in a relational database table may not share the same primary key value. It is tempting to believe that the leftmost column in a document table is a primary key, but as Table 8-6 illustrates, the leftmost column does not have to be unique.
In some cases, two columns may appear equally qualified to serve as the leftmost column. When this happens, the best solution is to present the same information in two separate tables. For example, suppose you are writing a document that compares UNIX and DOS. Further suppose that some members of the audience are more familiar with UNIX and others with DOS. Instead of flipping a coin, you should provide two tables like Tables 8-8 and 8-9.
TABLE 8-8 DOS Commands if You Already Know UNIX
Readers generally prefer alphabetical order over any other categorization scheme. Writers, for some strange reason, often organize tables using nonalphabetic schemes, generally because other schemes feel more "natural" to them. When a table isn't in alphabetical order, readers often get annoyed, trying to figure out the writer's scheme. When you have the luxury of time, consider providing the same information in two tables—one organized alphabetically and the other organized by some other organizational scheme. Alternatively, consider breaking a large table into a series of smaller tables, each representing a different category. Then, sort alphabetically within each small table.
i
78 Tables > Arrangement of Columns and Rows
Parallelism in Tables
"Parallel Lists" on page 70 describes the importance of parallelism in lists. In fact, this same concept is also important in tables. In particular, keep the text within all cells of a column parallel. To explore this idea, consider Table 8-10, in which every column is nonparallel.
In the preceding table, note the following problems:
• In the Family column, the first two entries are singular, but the last entry is plural.
• In the Fruit column, the first entry consists of an adjective and a noun. To be parallel, the second and third entries must contain one or more adjectives followed by a noun.
• In the Comments column, the first entry is a sentence that starts with a verb; therefore, the second and third entries should have the same form. Furthermore, since the first entry ends with a period, subsequent entries must end with a period. The phrase Produce turpentine and rosin isn't grammatically correct.
Table 8-11 shows a corrected, parallel version of Table 8-10.
Although tables must be parallel within columns; they do not have to be parallel between columns. For example, it is okay that all cells in the Family column are nouns, but all entries in the Comments column are verb phrases. Nevertheless, it is still a good idea for all entries throughout a table to be consistent in number (singular versus plural) and in tense.
Ill Tables > Parallelism in Tables 79
Amount of Text in Cells
Text in tables should be clear and highly concise. Never get long-winded inside a cell. For example, Table 8-12 contains too much text in each cell.
TABLE 8-12 Characteristics ot the Mulberry Family
Species
Fruit
Comments
The tree has scary-looking spikes. When several trees are planted close together, the hedge forms an impenetrable natural fence. Early American settlers created prized bows from the wood.
This tree provides exceptionally delicious fruit; however, humans rarely get to taste it. That is because birds and other animals adore it and will strip the tree of fruit the day before you harvest. If you can bear to chop it down, the tree's wood makes excellent fences.
In a few cases, when confronted with lengthy cells, you can simply edit down the text into more concise sentences. In most cases though, lengthy columns are a signal that you should convert the table into a series of paragraphs. Oftentimes, the leftmost column can serve as a section header for these paragraphs. For example, the following is a prose version of the preceding table.
Osage Orange
Osage orange trees produce a fruit having a bizarre, brainlike exterior. This fruit is about the size of a citrus orange.
The tree has scary-looking spikes. When several trees are planted close together, the hedge forms an impenetrable natural fence. Early American settlers created prized bows from the wood.
Red Mulberry
Red mulberries produce fruit that is similar to a large blackberry in shape, color, and taste. Most creatures find the fruit irresistible.
These trees provide exceptionally delicious fruit; however, humans rarely get to taste it. That is because birds and other animals adore it and will strip the tree of fruit the day before you harvest. If you can bear to chop it down, the tree's wood makes excellent fences.
80 Tables > Amount of Text in Cells
Rules
A rule is a line in a table that separates columns or rows. Table 8-13 contains a full complement of interior and exterior rules.
TABLE 8-13 A Ruled Table
If you create ruled tables, follow these guidelines:
• Use very thin lines for rules. Thick rules look clumsy. The only exception is that the top and bottom rules can be thicker to help mark the table's border.
• Provide a slightly thicker rule (or a double line) to separate the header row from the first body row.
The lines on the outside of the table are called exterior rules. Those in the middle are called interior rules. Some ruled tables omit exterior rules. If your table does contain exterior rules and interior rules, the exterior rules should be the same line width as the interior rules.
Are Ruled Tables Better?
Graphic artists generally detest rules, so rules have disappeared from many technical documents. Ruled tables look cluttered; unruled tables look cleaner. However, horizontal rules help guide a reader's eyes across a row. Horizontal rules (and to some extent, vertical rules) reduce reading mistakes.
Many organizations debate the value of rules. A reasonable compromise is to render tables that contain interior rules but do not contain exterior rules. Some organizations take it one step further, providing only horizontal rules to separate rows and omitting vertical rules that would separate columns.
So, I can't answer the question, are ruled tables better than unruled tables? The answer really comes down to form versus function. Unruled tables provide better form, while ruled tables are slightly more functional.
. 11*.
Shading
Row shading provides an aesthetically pleasing and highly effective alternative to rules. For example, consider the shading in Table 8-14.
TABLE 8-14 An Example That Uses Row Shading
In the preceding table, note the following patterns, which are typical of shaded tables:
• The header row uses a different shading pattern than the body rows. When color is an option, the background color of the header row is usually different from the background of the shaded body rows.
• Every other body row is shaded.
• The bottom and top rows of the table are ruled, which helps visually bound the table.
• Other than the top and bottom rows, shaded tables should not contain rules. Shading eliminates the need for rules.
I
82 Tables > Shading
Captions
Every table needs a table number and a useful caption. After all, readers who are skimming documents are far more likely to read table captions than the table introductions embedded inside paragraphs. Effective captions have the following characteristics:
• They are detailed enough to explain the purpose of the table but are still as concise as possible.
• They avoid repeating all the names of the table's columns (although you often must repeat at least one of the column names).
• They are self-sufficient, not dependent on the surrounding paragraphs. Note that readers' eyes often gravitate straight to tables and skip over the text that introduces the table.
Consider Table 8-15, which describes characteristics of three native North American trees that bear edible fruit.
Suboptimal captions for the preceding table would include the following:
• Native North American Fruit (This caption is not precise; many fruits are inedible.)
• North American Fruit Species, Heights, and Fruits (This caption just repeats the column names.)
A good caption for the preceding table is as follows:
• Characteristics of Some Native North American Fruit Trees
QUANTUM LEAP
Place table captions above the table. Place figure captions below the figure.
1 . Tables > Captions 83
Summary of Tables
When reviewing your tables, ask yourself the following questions:
• Are all tables numbered? The title of each table should contain a number, such as Table 6 or Table 12-5.
• Do all tables have a clear, accurate, helpful caption?
• Does each column contain a column header? Are all the column headers clear?
• Do all numerical column headers contain suitable units of measurement?
• Does the information in the leftmost column provide the best way to organize the table? Is the leftmost column in alphabetical order?
• Is the text within columns grammatically parallel?
• Is the text within certain cells too long? Should these cells be broken out into separate rows? Should the entire table be eliminated and replaced with prose? Is the table itself too long? Should the table be divided into multiple smaller tables?
I
84 Tables > Summary of Tables
I CHAPTER 9
Graphics
I picture is, of course, worth a thousand words. Unfortunately, creating professional-looking graphics often takes substantially longer than writing a thousand professional-sounding words. Nevertheless, the effort is usually worth it. Effective technical communication engages readers, and nothing engages readers like beautiful photographs, lucid graphs, or exotic illustrations. Few people—if being truly honest with themselves—will deny that they like looking at pictures more than reading text. True, the same people might learn more from the text, but there is something satisfying and easy about pictures, while text requires effort.
Wmp
V
>:*•
«
FIGURE 9-1 This picture is totally off topic, but you looked at it before you read the opening paragraph, simply because it is a picture.
Graphics 85
Time Series
A time series is a two-dimensional graph in which the x-axis represents the passage of time. The /-axis could represent just about anything. For example, consider the time series in Figure 9-2, which plots temperature in Mytown over a 14-day period.
100°-
■■■■■■■■,■'
M
I
20°.
I I I I I I I I I I I I I I
1 2 3 4 5 6 7 8 9 10 11 12 13 14
FIGURE 9-2 Daily extremes in Mytown from June 1 to June 14 (a faulty graph).
The preceding time series contains the following faults:
• The y-axis spans 100 degrees, yet the actual data only spans about 50 degrees. The compulsion to normalize graphs is very strong; however, starting the y-axis at zero wastes space, squishes data, and makes the graph less useful. Since so much space is wasted, it is harder to get an accurate read on individual data points.
• The guiding horizontal lines at 20° intervals are too thick and strong, taking the focus away from where it should be (on the data itself).
• The axes are only partially labeled. Without reading the caption, you can't tell what month this represents.
• The reader gets little sense of how this data relates to the norm. Was this period cooler or warmer than normal?
1%
86 Graphics > Time Series
Figure 9-3 improves upon Figure 9-2.
90°-
Temp. (F°)
70°-
60°
| actual range for this day Q normal range for this day
1 2 3 4 5 6 7 8 9 10 11 12 13 14 June 2005
FIGURE 9-3 Daily extremes in Mytown from June 1 to June 14 (better).
Figure 9-3 does a better job of illustrating detail but still does not help readers understand the aggregate. The detail obscures the big picture, making it difficult to determine whether temperatures were warmer or cooler than normal over this period. One simple solution is to add a textual summary announcing the deviation from the norm. An alternate solution is to add a second graph—such as the one shown in Figure 9-4—that focuses on the daily mean. By focusing on the mean, Figure 9-4 makes it easy to see various cool and warm periods and to realize that temperatures were above normal for the period.
90°
Temp. 70 o (F°)
50"
1 I above normal temperture | below normal temperture
1 I I I I I I I I I I I I I 1 2 3 4 5 6 7 8 9 10 11 12 13 14 June 2005
FIGURE 9-4 Actual versus expected mean temperatures in Mytown from June 1 to June 14.
1 i
Extra Detail In Online Graphics
The best graphics not only present immediate information but also provide a way for interested readers to dive down to a greater level of detail. Achieving this multilayered presentation is quite difficult in hard-copy graphics but relatively easy in online graphics. In a Web page, as the reader's mouse rolls over a region of the graph, further details about that region can pop up. For example, consider the graph shown in Figure 9-5. As a visitor rolls the cursor over June 6, a second window pops up to display additional information.
I
70°
60
50
Record high = 93 c
Normal mean = 68 ( 100
90° HI
80 °" 1 Record low = 44 c
82° = Actual high at 3:57 pm
73° = Actual mean
64° = Actual low at 6:18 am
June 6
In
ri~r~rr~nT
12 3 4 5 6 7
FIGURE9-5 Clicking on a date should provide details about that date.
It would have been possible for a single graph to represent all the information shown in the primary graph and the popup. However, the resulting graph would have been busy and cluttered. By separating the graphs, each graph stays relatively clean. Casual readers can view what they need, as can more serious viewers.
a
88 Graphics > Extra Detail in Online Graphics
Before and After
In a before-and-after sequence, lay out the two graphics side by side, with the "before" graphic on the left and the "after" graphic on the right (unless you are writing a manual for an audience that reads text from right to left). For example, consider the before-and-after figure shown in Figure 9-6.
FIGURE 9-6 Walrus mating groups before and after introduction of Pongo.
Many technical communicators mistakenly provide only the "after" picture, leaving readers grasping for the change. The before-and-after sequence in Figure 9-7 is more powerful than either picture by itself.
FIGURE 9-7 A wine bottle, before and after corking.
Callouts versus Embedded Text
Labeling the parts of a mechanical or biological unit is typically of great value to readers. To label the parts of a figure or photograph, rely on one of the following two mechanisms:
• callouts
• embedded labels
In a callout, the label is some distance away from the part. For example, Figure 9-8 contains four callouts. Most artists connect the label with the part by drawing a line segment. The keys to successful callouts are as follows:
• Keep the line segment short to avoid making the reader's eyes traverse a lot of real estate to connect the label with the part.
• Don't let line segments cross.
• When working in a color medium, render the line segments in a color that contrasts sharply with the figure.
Distal phalanx Middle phalanx
Proximal phalanx
\ \ Metacarpal
FIGURE 9-8 Using callouts to label bones In the human little finger.
Ill
90 Graphics > Callouts versus Embedded Text
An embedded label is affixed to the part itself. In other words, the label is stamped directly on the part. Therefore, an embedded label has no need of a line segment to connect the part to the label. For example, Figure 9-9 contains three embedded labels.
FIGURE 9-9 Using embedded labels to identify parts of the human digestive system.
An effective embedded label should not disturb the reader's view of the part itself. In Figure 9-9, for example, the embedded labels are small enough that they do not interfere with the outline shapes of the digestive organs, although the "Pancreas" label is awfully close to the border.
Callouts versus Embedded Labels
Most professional graphic artists greatly prefer callouts over embedded labels. When the parts you are labelling are skinny, you have no choice but to use callouts. For example, you cannot fit embedded labels inside the bones of your little finger.
As a technical communicator, I'm less concerned about the sanctity of artwork than about communicating effectively. Therefore, I do not feel quite as negatively about embedded labels as most professional graphic artists. In some cases, I feel that callouts force readers' eyes to work unnecessarily hard. For example, when a diagram contains many parts jumbled together like a jigsaw puzzle, it is easier to read embedded labels than to traverse a lengthy line segment to a callout label far, far away.
Graphics > Callouts versus Embedded Text 91
Graphics That Orient Readers
When walking in a highly touristed area, most people like to see the same map repeated every few blocks. The only thing that changes in these maps is the position of the blessedly comforting words You are here. You can use a similar mechanism to orient technical readers. Instead of a map, repeat the same block diagram at the start of each chapter in your book. In place of the magic words You are here, help readers get their bearings by highlighting the relevant section of the diagram.
For example, suppose your document contains an introductory chapter followed by three chapters, entitled "Canid," "Coyote," and "Gray Wolf." In this case, consider placing Figure 9-10 on page 1 of the introductory chapter.
Gray Wolf
Coyote
Canid
FIGURE 9-10 The figure you place in Chapter 1 of the book.
In each chapter, repeat the preceding figure, but highlight the relevant topic. For example, place Figure 9-11 at the beginning of the "Coyote" chapter.
Gray Wolf Coyote
Canid
FIGURE 9-11 The figure you place at the beginning of the "Coyote" chapter.
This method of presentation is simple to implement (after all, you only have to draw the picture once) and highly effective.