Spring into Technical Writing for Engineers and Scientists [Paperback ed.] 0131498630, 9780131498631

Citation preview

---

DRAFT MANUSCRIPT FINAL BOOKS AVAILABLE MID-MAY 2005

ii spring into

ii

the smart professional's choice

TECHNICAL WRITING for Engineers

and Scientists

Barry J.

ROSENBERG

Digitized by the Internet Archive in

2011

http://www.archive.org/details/springintotechniOOrose

spring into

Technical Writing for Engineers and

DRAFT MANUSCRIPT Books Available

May 2005 This manuscript has been provided by Pearson Education at this early stage to create awareness for this upcoming book. It has not been copyedited or proofread yet; we trust that you will

judge

this

book on technical

punctuation errors that

merit, not

will

be fixed

on grammatical and at a later stage.

part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form, or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior consent of the publisher.

No

All Pearson Education books are available at a discount for corporate bulk purchases. For information on bulk discounts, please call (800)428-5531.

Spring Into Technical Writing for Engineers and Scientists

Rosenberg, Barry

ISBN 0131498630

©

*

Paperback

*

J.

352 pages

2005 Pearson Education

Pearson Education Upper Saddle River, NJ • Boston • Indianapolis • San Francisco • Toronto • Montreal • London • Munich • Paris • Madrid Capetown • Sydney • Tokyo • Singapore • Mexico City

New York

series

spring into

Spring

Into... a series of short, concise, fast-paced tutorials for professionals

transitioning to

new

Find us online at

Spring Into

technologies.

www.awprofessional.com/springinto/

Windows XP

Service Pack 2

Brian Culp

ISBN 0-13-167983-X Spring Into

PHP 5

Steven Holzner ISBN 0-13-149862-2 Spring Into

Molly

E.

HTML and CSS

Holzschlag

ISBN 0-13-185586-7 Spring Into Technical Writing for Engineers and Scientists J. Rosenberg ISBN 0-13-149863-0

Barry

Spring Into Linux®

Janet Valade

ISBN 0-13-185354-6

YOUR OPINION IS IMPORTANT TO US! We would like to hear from you regarding the Spring Into... visit

www.awprofessional.com/springintosurvey/

Survey participants

will

to

Series. Please

complete our survey.

receive a special offer for sharing their opinions.

From the Series

Editor

Barry J. Rosenberg

A few years which

ago,

I

in a new job in new skills in a very to become an instant become instantly compe-

found myself

had to master many

I

short time. expert, but

I

I

didn't

have

did have to

tent. I

went

bookstore but

to the

was shocked by how

much

the publishing world had changed. At a

place

where

celebrated,

wit and intelligence had once

dummies were now

been

venerated.

What Photograph courtesy of Ed Raduns

happened? Well,

made

I

a

few phone

vinced Uncle Ed to lem. Actually,

books .

made

a

calls,

"

because

all

sew up a few costumes, and conOh wait... that was a different probsome really talented friends to write

got Aunt Barbara to

us use the barn as a stage.

few phone

that clever people wouldn't

.

Into.

I

let

calls

and got

be ashamed to read.

names were

the good

We

called the series "Spring

already taken.

With Spring Into..., we feel that we've created the perfect series for busy professionals. However, there's the rub we can't be sure unless you tell us. Maybe we're hitting the ball out of the park and straight through the uprights, bending it like Beckham, and finding nothing but net. On the other hand, maybe we've simply spun a twisted ball of

—

cliches.

Only you can

tell

us. Therefore,

mind about these books, please email

if

anything

me

— positive or negative —

is

on your

at

[email protected] I

promise not to add you to any email

address. Sincerely,

Barry

lists,

spam

you, or perform immoral acts with your

spring into

Technical Writing for Engineers and Scientists Barry J. Rosenberg

YrAddison-Wesley Upper Saddle

New York Capetown

•

•

River,

Nl

Toronto

Sydney

•

•

Boston

•

Indianapolis

Montreal

•

London

•

Tokyo

•

Singapore

•

-

•

San Francisco

Munich

•

Mexico City

Paris

•

Madrid

Many

of the designations used by manufacturers and

Where

are claimed as trademarks. lisher

sellers to distinguish their

was aware of a trademark claim, the designations have been printed with

ital letters

or in

products

those designations appear in this book, and the pubinitial

cap-

capitals.

all

The author and publisher have taken

care in the preparation of this book, but

make no

expressed or implied warranty of any kind and assume no responsibility for errors or omissions.

No

assumed

liability is

for incidental or consequential

damages

in

connection with

or arising out of the use of the information or programs contained herein.

The publisher

offers excellent discounts

purchases or special

content particular to ests.

on

this

book when ordered

in

quantity for bulk

which may include electronic versions and/or custom covers and your business, training goals, marketing focus, and branding inter-

sales,

For more information, please contact:

U.

S.

Corporate and Government Sales

(800) 382-3419

[email protected] For sales outside the U.

please contact:

S.,

International Sales

[email protected] Visit us

on the Web: www.awprofessional.com

Library of Congress Cataloging-in-Publication Data:

Rosenberg, Barry

J.

Spring into technical writing for engineers and scientists p.

/

Barry

J.

Rosenberg,

cm.

Includes bibliographical references and index.

ISBN 0-13-149863-0 1.

(alk.

Technical writing.

I.

paper)

Title.

T11.R663 2005

808'.0666—dc22 2005041173 Copyright

©

2005 Pearson Education,

All rights reserved. Printed in the

Inc.

United States of America. This publication

is

protected

by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding

permissions, write

to:

Pearson Education,

Inc.

Rights and Contracts Department

One

Lake Street

Upper Saddle

River,

NJ 07458

ISBN 0-13-149863-0 Text printed in the United States First printing,

May 2005

on

recycled paper Courier in Stoughton, Massachusetts.

Dedication

Contents

Preface

SECTION

1

CHAPTER

1

xvii

Planning to Write

1

The Quest

3

Technical Writing Theorems

Technical Writing Tell

Can Be

4

Creative

6

The Value of Technical Communication

Comparing Technical Writing

CHAPTER

CHAPTER

2

3

5

'Em to

You

to Engineering

Audience

and Science

7 8

9

General Education Level

10

Experience and Expertise

11

Breadth of Audience

12

Native Language

13

Native Culture

15

Audience Motivation

17

Medium and

18

the Message

Becoming the Audience

19

Summary

20

of Audience

Documentation Plans

21

Document Specifications Doc Doc Specs: Sample (

Specs)

Documentation Project Plans Documentation Project

Summary

Plan:

22 23 25

Sample

of Documentation Specifications

26 28

SECTION 2

Writing: General Principles

29

CHAPTER

Words

31

(argon

32

4

Contents

ix

Consistency

33

Verbs

34

Adjectives and Adverbs

36

37 38 39

Pronouns: He, She, and They Pronouns: You

Pronouns:

CHAPTER

5

It

and They

Fluffy Phrases

40

Commonly Confused Words Summary of Words

41

43

45

Sentences Active Voice and Passive Voice

46

Active Voice

47

When

Is

Is

Better

Passive Voice

Okay?

48

Short = Sweet

CHAPTER 6

49

Causes of Long Sentences

50

One

51

Sentence =

One Thought

Parenthetical Clauses

52

Summary of Sentences

53

Paragraphs and Sections

56

Paragraph Length

58

Paragraph Transitions

59

Sections

60

Summary of Paragraphs and

CHAPTER

7

Sections

Elements

61

63

Lists Bulleted Lists

CHAPTER 8

55

Sentence Transitions

in Bulleted Lists

64 65

The Length of Each Element

66

Numbered

67

Lists

Directions

68

Introductions to Lists

69

Parallel Lists

70

Summary of Lists

72

Tables

73

Column Headers

74

Units of Measure

75

Arrangement of Columns and Rows

77

Contents

Parallelism in Tables

Amount of Text

79 80

in Cells

Rules

81

Shading

82

Captions

83

Summary

CHAPTER

9

of Tables

84

85

Graphics

Time

86

Series

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 Technical Photography Line Art Enhances Technical Photographs Big Picture

First,

Then

Details

Layout: Controlling Focus Layout: Keeping Eyes

CHAPTER

10

99 100

on

the Page

101

102 104

106

Layout: White Space

1

Summary of Graphics

109

Professional Secrets

Ill

Explanations of Formula-Based Rules

112

Examples

114

Examples by Metaphor Examples

for

Programming Documentation

07

115

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

125

the

Obvious

Precision Descriptions

126

The Hardest

128

Summary

Part of Writing

of Professional Secrets

129

Contents

xi

SECTION 3 CHAPTER

11

Writing: Specific Kinds of

Documents

Manuals Manual

133

Style:

Cookbooks

1

Cookbook Example: Installing Manual Style: Tutorials

the

Carambola Server

Style:

Guides

Style:

Style:

HTML Headers

Reference Manuals

prime

Reference Example: The

Manual

140

Nonverbal Manuals

142

Online Help: Overview

143

Online Help: Best Practices

144

Online Help Examples

145

147

Release Notes Example:

Carambola

Web

Server Version 3.7

Preface

148

149

Prefaces

Example

150

Glossaries

151

Glossary Example: Tropical Weather Terms

152

Tables of Contents

153

Indexes

1

Indexes: Providing Concise Entries

156

Indexes: Permuting

12

139

141

Utility

Release Notes

CHAPTER

36

137

138

Guide Example: Creating

Manual

HTML

34

135 1

Tutorial Example: Getting Started with

Manual

131

Terms

1

55

57

Indexes: Providing Entries for Concepts

158

Summary of Manuals

159

Web

161

Sites

Plan Your

Home Home Home

Web

162

Site

Page: Specify Purpose

and Audience

Pages: Engage the Reader's Imagination Pages: Set the

Tone

164

166 167

Page Templates

1

68

Navigators and Search Boxes

1

70

Hyperlinks in Body Text

1

72

Secondary Pages

1

74

Web

Text

in

PDF

versus

Sites

175

HTML

176

Frequently Asked Questions (FAQs)

178

Summary of Web

1

Sites

80

i xii

Contents

CHAPTER

13

Proposals

181

The Proposal before

CHAPTER

CHAPTER

14

15

16

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

CHAPTER

the Proposal

Proposal: Example Marketing Section

197

Business Plans

198

Summary of Proposals

200

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

213

of Internal Planning Documents

Lab Reports

215

Abstract

216

Introduction

217

Materials

219

Experimental Procedure

220

Results

221

Discussion

223

Conclusion

224

References

225

Summary

226

of Lab Reports

227

PowerPoint Presentations 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

Introductory Slides:

Body

Slides:

An

Alternate Approach

Face and Variety

Mechanics: Fonts and Backgrounds

Body

CHAPTER

17

18

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

247

Presentations

249

E-Mail

The Essence of the E-mail Problem

250

Before Hitting the Send Button

252

Editing

Miscommunication

and Producing Documents

What

Is It

Work Superior's Work

Technical Editing a Peer's

259 261

262

Document Copyediting Your Own Document

263

Media

265

Copyediting

a

Colleague's

for Technical Editing

Bug-Tracking Systems

A

19

257

260

Really?

Technical Editing a

254

256

Editing and the Documentation Process Editing:

CHAPTER

235

Audience: The Theory of Relativity

Summary of E-mail

CHAPTER

234

236

Slides: Effective Lists

After the First

SECTION 4

233

264

266 267

Process for Editing

Beta Tests for Documentation

268

Summary of Editing and

269

the Documentation Process

Fonts and Typography

271

Serif and Sans-Serif Fonts

272

Fixed-Width versus Variable-Width Fonts

274

Serif and Sans-Serif in Serif

and Sans-Serif in

Font Height Italics

and Boldface

Hard Copy Soft

Copy

275

276 277

279

Contents

CHAPTER 20

Consistency and Convention

280

True-Type versus PostScript Fonts

281

Summary of Fonts and Typography

282

Punctuation

Commas

283 284

Dashes and Hyphens

285

Semicolons

286

Periods

287

Colons

288

Quotation Marks

289

Glossary

291

Bibliography

299

Index

301

Contents

xv

Preface

character of Fortuna

Ihe

—

brilliant,

sexy heiress to the Gambini empire, and two-

time winner of both the Grand Prix de ics

—

is

Monaco and

dead, implied or extrapolated, fictional or nonfictional

—

mathemat-

the Fields Prize in

strictly fictional. In fact, all the characters in this

—whether

book

are fictional.

living or

The people,

the

companies, the situations, and everything presented as 100% factual are completely tional. In fact,

don't even really exist; "Barry Rosenberg"

I

formed by the publishing company from

To be completely honest,

this

is

fic-

composite author

several actual technical authors.

fictional.

and asymptotically approaches

manager, and teacher working

just a

book contains no character named Fortuna.

about everything being fictional factual

is

The information

in this

book

All that stuff

the truth

is

and

satisfactual. I'm real, too. I'm a real technical writer,

in the software industry.

I

occasionally teach technical writ-

ing to engineering and science students at a surreal place called MIT.

Who I've

Should Read This Book?

aimed

this

book

engineers and scientists

at

who must

Perhaps you are an esteemed 60-year-old scientist ing

is

to the job.

Perhaps you are

who

a 20-year-old science

write about

has long realized

and you you

it

write,

me

and you

Much

good writer and would for engineers

and

that

same way

I

integral writ-

your job requires,

margin of everything a little easier.

your writing

scientists,

to write better. If you'd like to find out

book and who

the

is

like to take

how

taking sa class in

somewhere between those

to

another

level.

not professional writers.

you don't much care about the difference between

— you only want

for this

1.

that

is

wish that there were a way to make writing go

just

re-emphasize: this book

assumed verbs

is

and reports

are sick of your peers scribbling "I don't understand" in the

Perhaps you are already a Let

painful to write the specs

who

student

technical writing because "you have to." Perhaps your career

two points, and you find

stuff.

transitive

more about

and

I've

intransitive

the demographics

think you are, see Table 2-1.

that a nineteenth-century publishing syndicate

formed "Mark Twain."

Preface

How I've

Is

This Book Organized?

organized

this

book

into the following four sections:

introduces the field and explains

how

documentation.

•

Section

•

Section 2 teaches you the nuts and bolts of technical and scientific writing.

1

Section 3 explains

•

how

to plan

and

to write particular kinds of engineering

scientific

documents. •

Section 4 covers editing and producing documentation.

The book concludes with Section

Section

1:

1

a

glossary of writing terms.

contains the following chapters:

Planning to Write

How

Chapter

Title

Teaches You

1

The Quest

Understand what

2

Audience

Evaluate

whom

to...

this field

is all

you are writing

about.

for

along multiple

parameters.

Documentation Plans

3

Create documentation specs and documentation proiect plans.

Section 2 contains the following chapters:

Section

2: Writing:

General Principles

How

Chapter

Title

Teaches You

4

Words

Choose your words

5

Sentences

Create accurate, concise sentences,

6

Paragraphs and Sections

Produce proper paragraphs and sections.

7

Lists

Generate professional bulleted and numbered

8

Tables

Create well-organized tables.

9

Graphics

to...

carefully.

Create technical figures, illustrations, and photographs, and integrate

10

1 xviii

Preface

lists.

Professiona Secrets 1

Master

all

them

into a

document.

the tricks of the writing trade.

Section 3 details specific kinds of documents.

Section

Specific Kinds of

3: Writing:

contains the following chapters:

It

Documents

How

Chapter

Title

Teaches You

11

Manuals

Write five

12

Web

Create effective technical

13

Proposals

14

Internal Planning

Sell

Documents

specs that

15

Lab Reports

Create lab reports that editors

16

PowerPoint

Write and deliver a

Presentations

presentation.

Sites

to...

common

styles of manuals.

Web

sites.

Write research proposals, business plans, and book proposals.

will

lead to

good products. will like.

memorable and

effective

Write perfectly clear e-mail messages that won't lead

E-Mail

17

your own company on an idea and produce

to

flame wars.

Section 4 contains the following chapters:

Section

4: Editing

and Producing Documents

Teaches You How

Chapter

Title

18

Editing

and the Docu-

to...

Put documentation through a proper quality assur-

mentation Process

ance process.

19

Fonts and Typography

Pick the appropriate fonts.

20

Punctuation

Use the

right

marks

in

the right places.

What's Unusual about This Book? This book

—

like the

other books in the Spring

Into... Series

— provides

the following

eccentricities:

•

Each topic

•

Each chunk builds on the previous chunks

•

is

explained in a discrete one- or two-page unit called a chunk.

Most chunks contain one or more examples. the foundation for almost

•

in that chapter.

Many chunks contain if

sometimes

all

sidebars

useful technical

I

believe that

good examples provide

documents.

and "Quantum Leap"

sections,

which provide

helpful,

digressive, ancillary material.

Preface

—

1

assume

that

you are

busy person for

a very

whom

this

book was excruciatingly painful. To repay that

the

chunk

Finally,

of presenting information so that you can learn as rapidly as possible.

style

hope

I

the time spent in the very act of buying

incalculable opportunity cost, I've adopted

you'll find this

no matter what the topic

book fun

—boring

text

to read. If you've paid is

good money

book

for a

a slap in the face.

Writing a Book about Writing Books

had

I

psychology professor as an undergraduate. Three times

this great cognitive

every week, he lectured us on current research on memory. Without

middle of every

He followed

the

in

same

opthamologist, and

my

the

fail, in

he ran back to his office to fetch the notes he had forgotten.

lecture,

vein as

sister's

my

acne-scarred dermatologist,

my

cross-eyed

speech pathology professor, who had a regrettable

stuttering problem. All

those people haunted

the writing professor

back and asked, "Am sentence, then erase Writing suddenly

who I

it,

me

while

I

wrote this book.

I

kept wondering whether

couldn't write well. After writing each sentence,

practicing what I'm preaching?" Friends,

then rewrite

became

it,

and erase

it,

My

very difficult for me.

it

I

got ugly.

and on and on

it

I

was

stepped write a

I'd

would go.

self-doubt reached biblical

proportions.

Then

it

hit

me—

I

had become the audience.

had re-experienced the pain

I

This was a breakthrough because "becoming the audience"

is

one

of the

important states a technical or scientific writer can achieve. Yes, pain

May

I

write about something else

a subset of the

good.

now

Where Can You Download Examples Used You can download

is

of writing.

most

in

This Book?

examples from

this

book by browsing

to the following

URL: http://www.phptr.com/title/0131498630

What I

Is

Fake

in

the Examples?

am honor bound •

All

to proclaim the following disclaimers about the examples:

of the companies mentioned (Dexco Unlimited, Carambola Publishing, Pravda

Mills, Googieplex, Calispindex,

ination. If

I

and so

accidentally picked the

forth) in this

name of a

book

are figments of

real enterprise,

then

it

my

imag-

was purely

a

coincidence. •

The sample biographies used

•

The sample proposals and

in this

book

are of fictitious people.

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.

S Preface

Who

Me

Helped

reviewers,

Write This Book?

—

the publisher of this

all

of

Mark Taub

whom

Mary Lou Nohr

•

book

— wisely appointed

—

brilliant wit

of technical editing

and highly humorous responses

detailed

the following three primary

were completely amazing:

to

my

—who turned out

drafts.

Mary

Lou's

beautifully

comments

were,

themselves, of publishable quality.

Chris Sawyer-Laucanno

•

—

writing professor at

MIT

insightful

crucial criticism.

love kept

•

and techni-

poet, biographer, expert in ancient languages,

—who offered and Nicholas Cravetta —engineer and writer — whose tough

cal

me on

the straight

and narrow.

Much

of the material

four semesters giving

Julie

me

at

in this

MIT.

I

am

the opportunity

Nahil did

Other material

a

book originated from

and the guidance

wonderful job guiding

in this

a technical writing

for preparing

bel for

170 Systems

Finally,

me

random

I

taught for

this

to teach that course.

book through

book comes from conversations with

to the technical writing

for the technical writing

department

life.

its

final editorial phases.

great technical writers, includ-

and Judy Tirutz. Special thanks

ing Jim Garrison, Marietta Hitzemann, John Abbott,

Kenyon College and

course

indebted to Jim Paradis, Les Perelman, and Steve Strang for

Thanks

at

to

Rensselaer Polytechnic Institute

also to

Roger Stern and Arthur Lew-

props, information, and jokes. Gigantic thanks to the brilliant engineers at

who

served as the inspiration for

enormous thanks

to

my

details over the last year so that

wife Marilyn, I

much

who

of this book.

took care of

could have the time to write

far

this

too

many day-to-day

book.

Preface

xxi

SECTION

1

Planning to Write

t

"if

ihis section introduces the field of technical to evaluate

your target audience.

sional specifications for the

It

and

scientific writing,

concludes by showing you

documents you plan

then explains

how

how

to write profes-

to write.

'£

CHAPTER

1

The Quest

\hen a

I

meet someone

invariably

becomes

perfectly droll!

Do

us more.

And

technical

yet,

ilization.

at a

party and say that I'm a technical writer, there

good

tell

and

the center of attention.

scientific

and use them properly.

cial

(

communication

Preserving discoveries through writing

scientist or

never

You shuck oysters for a living?

me How

)

Inventing life-saving pharmaceuticals ricate

is

follow-up question. After an awkward silence, the person standing next to

is

means

is

one of the building blocks of civ-

that others can benefit

useless without clear descriptions of

How many

wonderful discoveries have been

engineer didn't or couldn't successfully describe the idea?

ideas have failed because

no one could explain how

from them.

how

lost

to fab-

because a

How many commerHow many

to use the product?

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 •

/

like

as the following:

writing fiction, but technical writing

nical writing can •

Engineers

be

dull,

but

and scientists cant

it

is

really uncreative

and

dull.

Indeed, tech-

doesn't have to be.

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

If

you asked

Theorems

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

•

Write concisely.

•

Engage your audience.

•

Help the

clearly.

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

audi-

ence 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

•

Eliminate unnecessary sentences or irrelevant concepts.

in active voice.

Since technical writing offers so few fundamental theorems and corollaries, to be

an easy

art to master.

Although,

if

you were

to apply this

same

it

would seem

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

rienced editor that you will truly learn to write well.

The following

ditty

—

a

paraphrase of

a

famous quote on diplomacy by

summarizes your quest: Technical communication

The

is

to write

and

geekiest things in the simplest way.

1 The Quest > Technical Writing Theorems

to say

Isaac

Goldberg

Can Be Creative

Technical Writing

Technical and scientific writing has a well-founded reputation for being dull. Consider the following passage, which

Hot

air.

frequently

aimed

dense than cold

air is less

than cold

is

into contact with

The preceding passage meets for the target audience

a

in

air sinks.

it

Since hot

the atmosphere, a

and

criteria for

lay readers

weighs air

lot of

less

and cold mixing

air

of air

good

writing.

It is

fairly

appropriate

might have trouble imagining the weight of air

concise. However, the biggest sin in the preceding passage

it is

does not engage the audience.

it

put hot air on a scale,

and cold

each other

few of the

(though

pressing against a scale), that

When you

air rises

which can cause interesting reactions.

results,

is

air.

Consequently, hot

come

at lay readers:

It

produces no spark; you can almost hear the reader

snoring.

Despite It

its

and

reputation, technical

really a

is

matter of mind-set

scientific writing

— you must

recitation of facts to provide a treat for

can be highly creative and engaging.

truly feel the obligation to

your audience. Injecting

life

go beyond

a

dry

into the preceding pas-

sage yields the following:

Did you ever watch a hawk beating his wings at air rises, flies

On

the

hawk gets

fly

over a highway on a hot day? He

That's because the air over the highway

flies is

so

easily, barely

very hot. Since hot

a free ride up. Conversely, cool air sinks. So,

when

the

hawk

over cooler terrain, he has to beat his wings extra hard.

a larger scale,

must take

Air

is

when

a big

mass

of hot air

meets

a big

mass

of cold

air,

our hawk

shelter from stormy weather.

The second passage •

all.

is

far

more engaging than

too abstract to visualize, but a

the

first

for the following reasons:

hawk bobbing up and down on

the air

is

easy

to visualize.

For

•

Many

•

The image of the soaring hawk provides

all

readers find stories about animals compelling.

forms of communication, remember

a

mnemonic

device for this lesson.

this lesson:

You cannot impart information unless you have the audience's attention.

The Quest > Technical Writing Can Be Creative

'Em

Tell

I

saw

a

famous folksinger

career spanning single

that

in

concert a few years ago. Although he has had a wide-ranging

many decades and

musical

styles, his

name

is

instantly identified with a

song that he wrote long ago. In concert, he sang a few songs and then mentioned

—before he could continue— he had

"a

little

piece of business" to attend

his face twitching, he scratched out a limp rendition of his

Before continuing, there

is

a

little

piece of business that

I

to.

Then, with

most popular song.

must attend

to. It

goes something

like this:

1.

Tell

'em what you're going to

2.

Tell

'em.

3.

Tell

'em what you told 'em.

The preceding

ditty

—

a folksy version

edly technical writing's greatest

an "F = ma" certainty. At the book

•

tell

It is

level,

'em.

of "introduction, body, conclusion"

Many engineers and

hit.

a useful

—

scientists recite this

formula for organizing writing

the opening chapter should introduce the

at the

is

undoubt-

formula with

following

book and

levels:

the closing

chapter should summarize the book's contents.

At the chapter

•

level,

the opening section should introduce the chapter's topic

the closing section should

Some

summarize the

writers use this formula right

down

to the

and

chapter.

paragraph

level.

Indeed, in certain kinds

Howmuch baggage to

of writing, paragraphs do benefit from a classic strong opening and closing sentence. ever,

good

technical prose emphasizes speed, so the formula imposes too

be practical

paragraph

at the

level.

Experimentation shows that audiences tend to remember

and the end of a session better than principles in both the introduction

in the middle.

Thus,

facts

it is

a

presented at the beginning

sound

idea to highlight key

and conclusion. Furthermore, repetition

is

essential for

learning.

The downsides

to this

formula are as follows:

not concise.

•

Repetition

•

Many writers produce wasteful

is

conclusions that are almost identical to the

introduction. •

Many

readers

now

i The Quest >

Tell

'Em

skip over

summary

sections (except in lab reports).

The Value

The difference between success and ability to

communicate

In engineering

and

Communication

of Technical

failure in the technical

world

is

to

You

generally the

effectively.

science, brilliant does not always equate to successful. In fact, brilliant

often equals frustrated.

Of course,

success

is

a very tricky concept to define

success might equal another's failure. Nevertheless,

I'll

—one

engineer's

define engineering success as having

one or more of the following parameters: •

The engineer

•

•

•

promoted

The engineer

is

paid significantly

The engineer

invents something that changes the world in a positive way.

The engineer

generally gets his or her

neers find this parameter

In

my opinion, more

to a

more than

way

position. his or her peers.

in technical

disagreements. (Some engi-

more precious than oxygen.)

successful engineers convey their ideas better than unsuccessful engineers.

Top management positions nicate

management

is

effectively

rising use of e-mail

in

engineering organizations are staffed by those

and more persuasively than

and

concisely has never been

their brilliant colleagues.

who commuDue to the

instant messaging in technical organizations, writing clearly

and

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:

•

Good

Successful projects require careful planning.

engineering teams produce

detailed engineering specifications prior to implementation.

produce detailed documentation specifications prior •

Successful projects require testing.

Good

technical writers

to writing.

Good engineering projects run beta tests to find Good technical writers beta test early ver-

defects in early versions of the product.

sions of documentation for feedback. •

Successful projects require iteration.

No

matter

how much planning precedes

imple-

mentation, engineering typically requires a certain amount of iteration to achieve perfection.

Good •

The

An

writers

principle of parsimony

ing, simpler •

old documentation adage recursively states, "Writing

and good engineers constantly

is

200

it

paramount.

In

how

can

I

improve

rewriting."

is

this?

both engineering and technical writ-

better.

Achieving parsimony engineering,

is

ask,

is difficult.

usually takes

lines. Similarly,

it

Elegance

much

can take

not cheap. For example, in software

is

longer to code an algorithm in 100 lines than in

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 create mathematical equations that ing,

predict

although readability formulas can estimate

mula can

predict whether writing

document •

model and

is

getting

humans

is

to read

a passage's

clear. Ultimately, the

and

act

on

in

most sciences

phenomena.

is

to

In technical writ-

audience

only true

level,

test

no

for-

of a

it.

Writing and science require different thought processes.

Scientists construct para-

digms 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

Q:

What

are the three

A: Location, location,

The

What

A:

Audience.

Get

most important things and the

it?

are the three

third

one

on the joke

technical writing variant

Q:

something

is

is

estate?

that important.

as follows:

most important things

See, technical writers are really concise,

your audience's needs

in real

isn't really

like this:

essential for writing

in

technical writing?

so...

ahh, forget

it.'

At any

rate, identifying

good documents. This chapter helps you

define your audience through a set of questions, such as the following:

If

•

What does my audience

•

What

you work

is

already

the native language of

for a

know about

my

this

technology?

audience?

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

too abstract for

is

consider pasting a picture of

Some

I.

The

writers find

realtors' version

it

is

someone

in

some

writers. To solve this

problem,

your target audience up on your monitor.

easier to write for an individual than for a collection of people.

funnier.

I

weep

for

my

profession.

Audience

9

General Education Level

How much

general education has your audience had? Did your audience attend high

school? College? Graduate school?

Readers prefer text that

makes readers

feel

is

appropriate for their general education

dumb. Writing too "low" makes

readers

level.

feel that

Writing too "high"

they are wasting their

time.

Most textbooks on writing

you

tell

to write long sentences for highly educated readers

short sentences for poorly educated readers. However, lengthy sentences have technical prose; the goal in technical writing

Most textbooks on writing educational readers

level. In

and

also

tell

you

is

to use vocabulary appropriate for

a limited, unsophisticated vocabulary for poorly educated readers. After

and absinthe

The ornately

to

compose sentences such

beautiful carriage

The preceding sentence whether

it

is,

sentences. Nevertheless,

if

you

words when your audience

if

since

it

fect

words

word

is

is

are comfortable,

well educated.

just

is

By

contrast,

morass

somewhat

limited,

because your audience

often the simplest word.

Audience > General Education Level

is

good

like

a

little

a big

words

word

is

in its place.

it

means

technical prose

to parse exceedingly

you can certainly mix

Sometimes

using multiple

like

a labyrinth.

do not have the patience

i 10

chaotically through the

at all) takes a while.

may spare you from

your writing vocabulary

falutin

words

as the following:

indeed, ornately beautiful; however, figuring out what

means anything

built for speed; technical readers

word

bumbled

all,

for their dictionaries after every sentence.

drunk on absinthe careening through

butterfly

(or

your readers'

fiction authors often ignore this principle, preferring beautifully ornate

labyrinth

in

always to produce short, clear sentences.

other words, use a broad, sophisticated vocabulary for highly educated

you don't want uneducated readers scrambling

Many

and

no place

in

the

is

complex

bona-fide "big"

most concise

On the other hand,

you should not force yourself

to use high-

highly educated. In technical writing, the per-

Experience and Expertise

How much

experience does your audience have with this technology or topic? Does

your audience already have formal training

If

your audience

they are

new

to

already mastered.

nyms

freely.

is

it.

in this

technology?

already familiar with the topic, you can start at a higher level than

Never disrespect

When

if

your audience lacks experience, you must carefully define

technical terms. For example, is

if

audience by explaining topics that they have

writing for an experienced audience, you can use jargon and acro-

Conversely,

the following passage

a trained

when

all

writing for an audience of professional programmers,

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

Programmers can use

this

Interface (API).

API to extend the features of our product or to integrate

other software products with our product. The APIs for our product are written Java, which

Alternatively,

is

a popular

many nonprogrammers do

not care about technical details, so a passage

the following (which completely omits the

We

provide manuals describing

features. In other words,

if

acronym API) might be

isn't

exactly

the product's

what you want, your

it.

Sometimes your audience has had plenty of negative experience. this

like

just as effective:

how your programmers can extend

our off-the-shelf product

programmers can customize

of

in

programming language.

Is

your audience skeptical

technology? Never ignore negative expectations. For example, consider the follow-

ing inoculation from a

cell

phone manual:

may have run into problems getting a signal from your previous cell phone. some cases, this was due to a lack of cell towers. Our continentwide network of You

towers ensures that you are always

in

range.

In

other cases, your old

cell

In

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

Are you writing for a tightly focused audience or

In

some

you can pin your audience down

situations,

example, when you are writing certainly experts

on

In other situations,

audience for a

ground.

Some

cell

for a

a lab report

on an

broad range

of

to a fairly precise

esoteric topic,

all

readers?

demographic. For

your readers are almost

the topic.

your audience

phone

user's

is

rather broad. For example, consider the breadth of

manual. The readers span a wide age and educational back-

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

consider a manual explaining

manual

this

expertise in

will

far

falls

administer a

somewhere

Windows

in

between. For example,

The core audience

system.

probably be professional system administrators with

Windows. However, many amateurs might

to administer their

It is

how to

PCs

at

also use this

for

amount of

a fair

manual

to learn

how

home.

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

•

Aim

a few

documentation

at the least

advanced chapters or sections

at

experienced readers.

experienced readers. Label these chapters

or sections explicitly as "For Advanced Readers." If

time and

money

are

no

object,

your organization should handle

writing two separate documents:

•

one aimed

at

inexperienced readers

•

one aimed

at

experienced readers

l 12

Audience > Breadth

of

Audience

a

broad audience by

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 technical audiences

comprehend

ences in the United

Kingdom or United

How

Pervasive

Is

many European

countries,

technical prose written in English almost as well as audi States.

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,

him

to

in

Danish.

He answers me

in

"I

speak

Swedish. And when we are having trouble

understanding each other, we speak English."

Many

languages

—Chinese,

for

example

countries, technologists often have

—

more

are

markedly different from English.

difficulty

European countries. Many nonnative readers

will

understanding English

text

In such

than in

miss nuances. Note that small misun-

derstandings 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 ing for native speakers,

it is

— even the annoying ones. For example, when

okay

to split infinitives.

However,

split infinitives

writ-

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

sion 2 does not. Nonnative speakers will generally find version 2 far easier to under-

stand than version

1.

2.

1.

The

filter

causes high-frequency notes to gently and sweetly pass.

The

filter

causes high-frequency notes

to

pass gently and sweetly.

1 Audience > Native Language

13

Avoid

uncommon

acronyms.

(It is

common acronyms.) uncommon acronyms, but

Native English

fine to use

speakers can often guess the meaning of

such acronyms

cause problems for nonnative speakers.

Simplify vocabulary. Generally speaking, nonnative speakers have a somewhat smaller English vocabulary than native speakers.

What

Is

Which

a Simple

Word? verbs

of the following

•

use

•

utilize

•

employ

Native English speakers

simplest?

is

certainly pick "use" as the simplest.

will

shortest and the most commonly...

choose

differently

common

er...

because the verbs

It is,

after

all,

the

used. Native French speakers, however, might

and "employ" are cognates

"utilize"

for

French verbs.

Writing for Nontechnical Nonnative Speakers

When

writing for a nonnative audience of nontechnologists, you cannot assume that your

many many

readers understand English. True,

understand English very zation

must

translate the

well,

but

of your readers (particularly Europeans) will readers will not. In such situations, your organi-

documentation into your

For example, the documentation

set for a large

readers' native languages.

software product might consist of the

fol-

lowing:

•

Manuals

for

programmers and system administrators, which do not have

to be

translated. •

Manuals and online help

In certain situations,

for

end

users,

documentation can consist

to be translated. For example, directions for

given through pictures only.

li 14

which do have

Audience > Native Language

to be translated.

entirely of graphics,

unpacking

a

which would not have

shipping container might be

Native Culture

What percentage

your audience

ot

will

understand your cultural references?

Writers sometimes mistakenly assume that because readers share the same language, they also share the for a

same

culture.

The key

worldwide audience are

producing useful technical or

rules for

scientific

prose

as follows:

•

Avoid slang.

•

Pick examples and metaphors that will

make

•

Be sensitive to fundamental differences

in presentation.

•

Don't offend.

sense in multiple cultures.

Slang Even

among

tralians

native English speakers, slang

do not always understand each

is

often confusing

other's lingo.

(What

—

Brits,

in the

Americans, and Aus-

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

British readers, of course,

Many writers

feel that

game and

Okay

Is

would say

that a baseball

metaphor

just isn't cricket.

soccer/football terms are cross-cultural since the

Be aware, however, that a soccer

run for the company.

many American

that soccer slang

is

readers

would rather

game

is

"universal."

eat a soccer ball than

go to

not okay for an American audience.

Okay

Mysteriously, just about everyone

word okay or OK.

In fact, this

seems

word

is

to

know the meaning

so okay that

it

of the

American slang

has crept into the slang

of other

languages.

Audience > Native Culture

15

Examples Despite assurances to the contrary, place. ple,

It is

it

turns out that the world

hard to create examples that

will

make

is

actually an awfully big

sense everywhere in the world. For exam-

consider the following seemingly benign passage:

When an

electric force is applied, the

the balance

charge

is

charge

in

much

a capacitor increases,

way

the

your checking account increases when you work. Then, when the

in

needed, the capacitor releases

much

it,

the way you release the value

in

your checking account by writing a check.

Is

the preceding example cross-culturally correct? Unfortunately

ing accounts are

some

unknown

in Japan. Before investing too

it is

not. Personal check-

much energy

in

an example, do

research.

An Almost-Universal Earthlings

we do share gardens

in

Cultural Reference

do not share a common

religion, language, or political

a knowledge of American movies.

Kyoto or tea plantations

in India,

Many

system. However,

readers are unfamiliar with rock

but most

know who R2D2

is.

Presentation

We

often forget that

many

daily details are not universal. For example, consider the fol-

lowing date:

1/3/05

American readers pret

it

as

out the

1

1

interpret the preceding date as January 3, 2005.

European readers

March, 2005. To prevent cross-cultural confusion on dates,

month

as in the following

it is

inter-

clearer to spell

example:

March 2005

Some countries present monetary values money with real numbers. Some cultures a large

as integers only, while other countries express

use

commas

to separate groups of three digits in

number, but other cultures use periods. To avoid confusion, you may need

vide multiple examples of the

same

to pro-

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.

16

For instance,

when documenting

Audience > Native Culture

high-fat diets,

it

is

fine to depict

meat.

Audience Motivation

Audiences read

because they want

fiction

to

and technical prose because they have

to.

Writers often forget to ask themselves

The following

place.

list

provides

why

readers are picking

up

document

a

in the first

few general answers:

a

how to do something. Readers study manuals to learn new telescope, cook with a new microwave oven, or write code new programming language.

People read manuals to learn

•

how in a

to see

through

a

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

•

and

When

to consider their next

planning

What

Is

Quickly

a

document, always consider your

now— what

is

evaluate colleagues' progress,

readers' motivations.

the emotional state of

who has

someone reading the "How

an automobile owner's manual?

looking up fatal error codes

patient

field, to

Your Audience's Emotional State?

Flat Tire" section of is

keep up with their

experimental steps.

in

How

maniacal

the back of a software manual?

just received a distressing diagnosis

be able

to

is

How

to

Change

the reader

a

who

well will a

comprehend

a

doctor's instructions? Entire

manuals

situations, •

will

never be read

remember the

until disaster strikes.

When

writing about troubling

following:

Agitated readers are not always thinking rationally. You might need to start certain sections by reassuring the reader that the current

•

Agitated readers are probably

in

a highly impatient

problem

is

fixable.

mood. You must provide

concise answers.

To help agitated readers, consider the following suggestions: •

Provide a "Troubleshooting" section

•

Make sure

that various kinds of

in

manuals.

emergencies have entries

in

the index and

table of contents.

Audience > Audience Motivation

17

Medium and

Is

the Message

your target audience reading the document

in

hard copy or soft copy?

copy, does the technology permit hyperlinks? Will people read this or

I

in

linearly

random-access fashion?

a

don't honestly believe that the

medium

is

the message.) Nevertheless, the wise writer

ument

in soft

If

document

will

the message. is

lean towards the message being

(I

aware of the

medium through which

the doc-

be read.

One obvious

advantage of writing for the

hyperlinks, you can rely ularly useful

on other sources

when your audience

is

Web to

is

tell

that

you can provide hyperlinks. With

parts of the story. Hyperlinks are partic-

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

with your document, or will a hyperlink carry them there? Restating the question,

much

will

start

how

your readers already have read about the topic prior to hitting your document?

—

isn't dead not yet, anyway. Although paper offers many disadvantages, it does 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

Hard copy

offer

more

solid

strikes

Is

and

reliable. Legal transactions generally

still

require paper. Paper just plain

people as being more "real" than soft copy.

your audience going to read your document straight through, from cover to cover? Prob-

ably not.

Modern audiences

straight through.

That

is

Most

just

do not have the time or patience

technical readers snack, nibbling

not to say that straight, linear access

is

on

a

to read

documentation

page here and a chapter there.

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 quotes, sidebars, or photographs to pull in readers.

18

Audience > Medium and the Message

to use attention grabbers

such as

Becoming the Audience In teaching a task that requires great concentration, teachers

imagine themselves

sometimes

tell

students to

of the object being manipulated. Thus, the sculptor imag-

in the role

and the archer "becomes" the arrow.

ines the sculpture as an extension of herself, nical writing, the wise author periodically

author periodically stops writing and

becomes

starts

In tech-

the audience. In other words, the

reading and relating to the prose as the audi-

ence would.

Gaining empathy

for the reader

menting how what step

is

it

back and ask yourself,

do the things ates a

that

the expert

who

be the doctor

The best way to become

—

if

I

writer to learn.

were

that

you invented, you must imagine

in this doctor's shoes,

the audience

is,

new Application Programming

how

this

You must

has never seen this device before. You must frequently

literally,

to

become

would

The

Interface (API).

I

understand

the audience. That

your audience would do. For example, suppose

be to document only

mer would make

skill for a

and the novice. For example, while docu-

new medical instrument

to operate a

like to

probably the hardest

is

simultaneously be of two minds

a software

classic writer's

is,

this?

you must

engineer cre-

mistake would

API works instead of documenting how another program-

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

Through

writer should use the API exactly as her readers would.

would

how

learn not only

on using

itations

Walking a Mile

this experience, the writer

would

also learn various lim-

product.

this

in

the product should work, but she

a Reader's Shoes

to become the audience in a literal way. Nevertheless, empathy by reading similar documents immediately prior to writing your own document. For example, suppose you must write a spec for your It

is

sometimes impractical

you can

still

gain

colleagues. Immediately prior to writing, consider reading a couple of old specs that

your colleagues wrote. What did you

What

irritated

like

about their specs? What confused you?

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

Becoming ice

truly empathetic

and back

again. This

someone other than

is

is

difficult. After all,

it is

a

to.

long round-trip from expert to nov-

one of the primary reasons

that writing

is

often best

done by

the inventor.

Audience > Becoming the Audience

19

Summary

of

As you prepare to

write,

Table 2-1.

I've

2-1

it is

helpful to

taken the liberty of

book. Note that

TABLE

Audience

I

filling

out an audience chart such as that shown in

fill it

out based on the planning

Target Audience for This

The target audience on average holds mainly

ter's degree, tific

experience does the target audi-

ence have with technical or

scientific writing?

in

least

in

the target audience's predisposition

toward the subject matter?

in

some

the target audience has had at technical writing experience,

lot of

A few readers

experience. Almost no one

the target audience

The maiority

scientific writing to

The

the target audience tightly focused or

broad?

in

of

an expert.

and

be a chore; a smallish

it.

target audience

terms

is

of readers find technical

minority enjoy Is

mas-

discipline.

Everyone

have had a

is

a

a technical or scien-

either at school or at work.

What

target audience.

Answer general education has the target

audience had?

How much

did for writing this

Book

Question

How much

1

had the advantage of extensive market research on the

is

reasonably focused

mathematical and analytical

aptitude.

What percentage

of the target

Approximately

audience

85%

reads English as a native

language. The remaining

reads English as a native language?

people

who

15%

are technical

are comfortable reading (and

writing) English.

What percentage understand

of the target

my American

audience

will

cultural references?

Approximately lives or

25%

has

live

75%

lived in

elsewhere,

of the target

audience

North America. Since I

must be

careful about

cultural references.

What kinds

of

examples

will

the target audi-

ence prefer?

The target audience prefers ples.

scientific

exam-

However, since the audience comes

from a wide variety

of disciplines,

I

should

use examples about general scientific principles that

Why

is

the target audience reading this

book?

most readers

will

know.

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

tation plans:

•

documentation specifications (doc specs), which

•

documentation project plans, which

detail a single

detail a set of

documents

Documentation professionals ostensibly write these plans

mechanism before

it is

carefully

my

ever,

to provide a formal feedback

for other people in an enterprise. In other words, these plans provide a

head of engineering or

for the

document

written. Indeed,

and integrate

a

marketing representative to sway what

some organizations

their review into the

really

will

way

be written

do review documentation plans very

broader engineering development

experience suggests that you should write documentation plans for a

cycle.

more

Howvalu-

able reason:

Documentation plans lead

Even will

if

no one reads them

still

to better final

(hey,

it

documents.

could happen), writing detailed documentation plans

help you, the writer.

This chapter teaches you

how

to write

both kinds of planning documents.

Documentation Plans

21

Document Before writing

a

Specifications (Doc Specs)

document longer than 25 pages or

ification (doc spec).

A good doc

so,

you should create

•

It

helps you organize your thoughts about the document.

•

It

communicates your intentions

•

It

helps your team reach consensus

you

Ideally, creating a

document

to the other

spec-

members of the engineering team.

on the purpose and scope of the document before

The engineering adage about measuring twice and

start writing.

also applies to

a

spec serves the following three purposes:

cutting once

documentation.

doc spec involves the following three-step process:

1.

You

2.

Your reviewers analyze the preliminary doc spec.

3.

You generate

create a preliminary

a final

doc

spec.

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,

ments than long ones. A doc spec

A doc spec for a

pages long. outlines).

short doc specs generally yield a better harvest of com-

for a

50-page manual should only be about two or three

longer manual should be only slightly longer (due to lengthier

Each doc spec should contain the following sections:

•

a brief overview of the project

•

a detailed description

•

a brief description

•

a section entitled

•

an estimate of the length of the

•

the tools you will use to write the

(PDF,

HTML,

of the target audience

of the nongoals

"What Readers

final

topics that won't be covered in the

Know

after

document

and/or hard copy)

some of the

optionally, a brief discussion of

•

a fairly detailed outline, preferably

•

a

•

outstanding issues

•

a

down

finer points, such as tone

and pace

to first-level heads within each chapter

of reviewers and their responsibilities

schedule (omitted from the sample doc spec that follows)

lit 22

document

Reading This Document

document, plus the document's output media

•

list

—

Will

Documentation Plans > Document Specifications (Doc Specs)

Doc Specs: Sample Our engineering team doc spec describes

plans to

manual

a

roll

out the Carambola 3000 Weather Station in May. This

entitled Installing the

Carambola 3000 Weather

Station.

Target Audience

We

are

•

aiming the 3000

About

80%

about $200 on •

at the

high-end amateur market. This market

of this market consists of hobbyists a high-quality

About 20% of the audience need

a

who

are serious

is

split as follows:

enough

to

spend

weather station.

consist of community organizations such as schools that

weather station but do not have the budget for a professional model.

The hobbyists know what they matic diagram and skip the

are doing mechanically;

text.

most of them

The community organizations

will

look

at

the sche-

will require the detailed

text.

The reader must

also install

and configure the software.

comfortable installing software from

a

CD

We

assume

that

all

readers are

onto Microsoft Windows; however, we do not

assume any knowledge of computers beyond

that. So, the

guide must patiently explain con-

figuration.

Nongoals

Our

target audience already

no attempt

to explain

What Readers

Will

understands meteorological concepts, so the book

Know

after

make

Reading the Manual

After reading this manual, readers will

•

will

weather terms or weather forecasting.

Install the tangible parts

know how

to

do

the following:

of the weather station.

and configure the accompanying software.

•

Install

•

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

Visio Professional 2000. After finishing,

we

7.1

and produce diagrams with Microsoft

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

with a wire-o binding.

We

will kit the

on

a 6.5

X9

manuals with the product on the assembly

trii

floor.

Outline

The following

the preliminary outline (subject to change):

is

•

Front matter

•

Chapter

(title

page, copyright page, table of contents, preface)

Overview

1:

-

Capabilities

-

List

of Parts

- Schematic Diagram •

Chapter

The Weather

2:

Station

- Control Box and Power - Anemometer Unit - Hygrometer/Thermometer/Barometer Unit - Rain Gauge •

Chapter

Software

3:

-

Installation

-

Basic Configuration

- Connecting

to the Internet

•

Appending

•

Back matter (index, tear-out warranty card)

A: Troubleshooting

Reviewers

The following people have been graciously volunteered •

Eswar

•

Andy

•

Martina

will

will

review Chapter

1

and

to review the

manual:

2.

review Chapter 3 and Appendix A.

will

perform

a literary edit.

Outstanding Issues

We

cannot write Chapter 3 until the software has been developed. Given the software

development schedule, we Marketing must

will

finalize the

have limited time to write Chapter

new

tear-out warranty card

1 24

Documentation Plans > Doc Specs: Sample

3.

and terms prior

to

October

15.

Documentation Project Plans A

doc spec

details a single

documentation is

set,

document;

how

explaining

a

documentation project plan summarizes an

different pieces of the puzzle

fit

entire

together. If your

team

writing multiple documents, you should create a documentation project plan. Like a doc

spec, a

good documentation

project plan

team and helps bring the team

One way

documentation

to plan a

then to figure out which

would the

title(s)

necessitates multiple

Another way 1.

set

is

to identify

all

the audiences

you must

satisfy

and

title.

However,

this

is

not always possible. For example,

different kinds of information at different stages,

which

titles.

to plan a

documentation

Create a comprehensive

list

set is to

use a spreadsheet as follows:

of everything that users need to do, one item per row.

column, identify the audience

2.

In a separate

3.

Sort the rows by audience.

4.

Group

all

to the rest of the

they need. In the best possible world, each type of user

find everything in a single

same audience often needs

communicates your intentions

to consensus.

for each row.

the items related by audience into a

How Many Documents Are

title,

or possibly, into multiple

titles.

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

regardless of length) generates various fixed costs, so reducing the

reduce the

will

A

title

number

(any

title,

of titles

total cost.

documentation project plan needs documentation

to express the following:

•

the titles in the

•

a

few sentences about each

•

a

media plan, explaining how each

•

any outstanding issues

•

a

set,

preferably arranged by target audience

title

title will

be delivered to the target audience

schedule (omitted from the sample documentation project plan that follows)

Documentation Plans > Documentation Project Plans

25

Documentation Project Plan: Sample Our engineering team

plans to

out the Carambola 3000 Weather Station in May. This

roll

documentation project plan summarizes the planned documentation

The Documentation Set The documentation set will

TABLE

3-1

The

Titles in the

consist of the

titles listed in

Carambola 3000 Weather Station Documentation Set Title

Planning for the Carambola Installing the

3000 Weather

Abbreviation

Planning

Station

Carambola 3000 Weather Station

Installing

Release Notes

Release Notes

Developing Applications

Integrators

product.

Table 3-1.

Full Title

Customers

set for the

for the

Carambola 3000

Developing

Weather Station

Carambola 3000

Customer Support Reps

Advanced Troubleshooting Weather Station

Manufacturing

Schematics

Schematics

Hardware Specifications

Specs

We detail

each of the preceding

titles in

for the

Advanced Troubleshooting

separate doc specs, which you can find

on the cor-

porate intranet.

For

Consumers

We

will

•

provide the following three

Planning

—This guide

titles

will help

for customers:

consumers prepare

for

an installation during the

three-week interim between ordering the station and receiving

consumers determine the most •

—This guide

Installing

will help

it.

This guide will help

effective locations for instruments.

consumers

install the

hardware and

to install

and

configure the software. •

—These notes

Release Notes

known

summarize the

will

features of the product

bugs. (For subsequent releases, Release Notes will also

For Integrators

We

26

will

provide the following single

title

for integrators:

Documentation Plans > Documentation Project Plan: Sample

and

detail

document bugs

any

fixed.)

•

Developing grate the

— This

is

a

guide that

Carambola 3U00 with

software). This

book

will detail

their

our APIs

for

companies that want

to inte-

products (for example, with factory automation

contain several example programs written in Java.

will

Customer Support

We will •

provide the following documentation for our

Advanced Troubleshooting

—This guide

customer complaints. Note that the ing" chapter, but the

own customer

will explain

how

manual

Installing

to

support organization:

handle various potential

also contains a "Troubleshoot-

Advanced Troubleshooting guide contains solutions (including

remote debugging) that require more sophisticated knowledge of

Although we also find

will target Release

them

we

Notes for consumers,

internals.

believe that customer support will

helpful.

Manufacturing

We will •

provide the following information for our manufacturing and procurement teams:

Schematics

—These

will consist

of highly detailed schematic diagrams; our manufac-

turing team requires these schematics to assemble the product. •

Specs

— These documents contain tolerances and

specifications for

all

hardware com-

ponents; our procurement department requires these documents.

Media

We

will ship

TABLE 3-2 Title

documents

How We

in the

formats

Will Distribute

Abbreviation

Planning

listed in

Table 3-2.

the Documentation Set

Medium PDF

file

Distribution

We

will

e-mail this

file

to

consumers

right after

they buy the product. Installing

Hard copy

We

Release Notes

TXT

file

This

will

be on the installation CD.

Developing

PDF

file

This

will

be on the installation CD.

Advanced Troubleshooting

PDF

file

We

will

post this on our corporate intranet.

Schematics

VSD

files

We

will

post this on our corporate intranet.

Specs

PDF

file

We

will

post this on our corporate intranet.

will kit

these on the factory

floor.

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

Documentation Specifications

of

Before sending out your doc spec for review, ask yourself the following questions:

•

Are the right people on your distribution is

not on the distribution

tribution

list? (If

Conversely,

list?

list?

Will anyone be offended

he or she

if

do you have too many people on your

you put too many people on the

list,

many

then

dis-

readers will not

bother reviewing the doc spec because they will assume that someone else will do •

Is

the schedule achievable?

ever written

Can you

documents of this

really write a first draft that quickly?

size before? If not, give yourself

•

Does your outline contain ics

all

this

Have you

plenty of cushion

writing might take longer than you think. Have you allotted a suitable

time (not too long and not too short) for others to review

it.)

amount of

document?

the topics that your target audience needs? Are the top-

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

•

Do you

set

cover

all

audience segments?

have the right amount of information for each segment of the target audi-

ence? In other words, does the proposed documentation set meet the needs of

segments? Typically, the honest answer to this question

•

is

meet the needs of the primary segment?

documentation

set

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

all

no. In this case, does the

Documentation Specifications

SECTION 2

Writing: Genera Principles


Jargon

A

frans/stors,

which are tiny circuits that boost weak signals

transistor can turn a whisper into a scream.

into

Consistency

Renaming same

midstream

a part in

part throughout the

get" in Chapter

1,

will drive

your readers crazy; use the same name for the

document. For example,

don't refer to that

same part

if

you

refer to a certain part as a

as a "gadget" in

Chapter

2.

Once

"wid-

a widget,

sistent in

Remember that case is also part of a name. Therefore, you must be conhow you represent the case of a name. For example, a widget cannot suddenly

become

Widget or (horrors!)

always

widget.

a

a

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

loading

is

Many

as the thingy

and then

to a

programming but awful

useful in

completely different part as the in technical

of you are probably thinking that the preceding two paragraphs are just

sense and that no engineer or technical writer

and renaming errors writer's fault first

would do such

fault lies

with the people

who

common

a thing. In fact, overloading

are present in almost every technical manual. Oftentimes,

— sometimes the

Over-

thitigy.

communication.

originated the

it

isn't

names

the

in the

place.

Acronyms provide another prime opportunity example,

sion. For

I

once worked

at a

for overloading, inconsistency,

company

that overloaded the

bolize four different products or technologies. As

symbolize one

When new between

sym-

writers learn about the importance of variety in writing, they often oscillate

a technology's full its

name and

acronym,

its

acronym.

When

as in the following

you

first

introduce a term, you

example:

A Relational Database Management System (RDBMS) uses in

to

you can guess, an acronym should only

entity.

should also introduce

data

and confu-

acronym PS

a table

metaphor

to store

rows and columns.

After the initial use, you should pick exclusively. For

sion, Relational

one version

example, the acronym

RDBMS

is

— the more natural version—and use far

more

it

natural than the expanded ver-

Database Management System.

lit

Words > Consistency

33

Verbs

When

picking verbs, follow these guidelines:

•

Choose strong

•

Avoid overusing forms of

•

Provide variety in your choice of verbs.

•

Use the same tense throughout the document.

verbs. to be.

Choose Strong Verbs Strong verbs pack muscle and energy, moving the reader into action. Strong verbs are specific, precise,

sloth.

and dynamic. Weak verbs

lie listless

and dormant, generating boredom and

Avoid the following famously weak verbs:

•

to occur

•

to

happen

The preceding generic verbs

don't convey anything specific

the following variants, noticing

1.

2.

If

— they

just

happen. Compare

powerful version 2 sounds than version

you spread organic compost and limestone, bigger vegetables

1:

will occur.

Spreading organic compost and limestone generates bigger vegetables.

Avoid Overusing To

Although the verb reach for

how much more

it

Be be

to

is

fundamental and

automatically just because

essential,

you must not overuse

so handy. Note that

it is

to

it.

Many writers

be simply exists;

it

does

not describe.

Many

writers

team up

This combination

is

to

be with the generic

stronger pull of version 2 over version

1.

2.

There

The

is

noun

there to

produce there

(is) in

a gravitational force that pulls on satellites.

Earth's gravitational force pulls

version

HI 34

Words > Verbs

or there are.

1:

on

satellites.

Version 2 replaces a generic subject (There) with a specific subject

verb

is

very weak. For example, compare the following variants, noticing the

1

disappears in version

2.

(

The Earth). The weak

The wise writer keeps

there

is

and

there are to a

rewrite this construction into something

more

minimum. When

editing or revising,

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

the molecular structure of ethyl alcohol, which

1 illustrates

Figure 2

illustrates

raspberries. Figure 3

The

topic

is

tasty,

illustrates

the molecular structure

is

the

tenses (like the following)

is

require

present tense

by

a

illustrates

or...

is

for

all

verbs within a paragraph. Paragraphs that

mix

sound amateurish:

high sea-surface temperatures. Another requirement was favorable

high-level winds. With light

The

of using

Same Tense

You should maintain the same tense

Hurricanes

also plagued

that's a different topic.) Instead

three times in a row, try specifies or shows or presents or exemplifies

in

like

of...

but the verbs are monotonous. (Each sentence

monotonous grammatical format, but

Keep Verbs

an intoxicant.

is

the molecular structure of methanoate, which smells

winds

aloft,

hurricanes

will

gain

power.

usually the wisest choice for technical prose. However, the past tense

appropriate for portions of lab reports. After

all,

lab reports describe

what has previously

transpired.

You should generally maintain the same tense throughout an tors are extremely insistent

consider a

book

on

this point.

I

prefer a

entire

that describes previous research, present research,

research. Clearly, such a

book

document. Some

edi-

more pragmatic approach. For example, and potential future

requires multiple tenses.

Words > Verbs

35

Adjectives and Adverbs

Good just

technical prose ladles in healthy doses of verbs

and nouns and generally sprinkles

an occasional dash of adjectives and adverbs. This

adverbs can spice a dull dish to

made

life.

Our video board

extremely

is

The phrase "extremely

fast"

a

and adverbs. For example, consider the

When you

fol-

hardware manual:

fast.

smacks of marketing-speak, which

minds. Once the seeds of doubt are planted, engineers skeptically.

in

and

a real pity since adjectives

Unfortunately though, marketing and advertising have

technical people suspicious of adjectives

lowing misguided passage from

is

are writing for engineers

and

will

doubts

raises

in engineers'

view the remainder of the

scientists,

it is

much

text

wiser to stick to

objective, numerically based facts; for example:

Our video board can render

1.2 million

The preceding sentence presents an or her

own

Let the

polygons per minute.

objective fact,

which allows the reader to come

conclusions. Analytical people greatly prefer to

mantra

"Just the facts,

ma'am" echo

come

to their

across your brain as

Before going overboard, note that certain uses of adjectives are just adjectives to describe physical appearance

bomb-defusal manual

Similarly, occasional adverbs specific.

Adding a second

36

and adverb phrases

annoy technical

CPU

will

write.

fine.

For example, using

The following passage adjectives (red

and

Words > Adjectives and Adverbs

— from

a

blue):

are also fine, as long as they are objective

{70%-90% more quickly)

in the following sen-

readers:

make our

to his

conclusions.

only.

For example, the adverb phrase

tence will not

essential.

—would be catastrophic without

Never cut the blue wire; cut the red wire

and

is

you

own

software run

70%-90% more

quickly.

Pronouns: He, She, and They

The pronouns he and which are aimed

at

she

stir

up plenty of

someone other than

trouble. Consider the following variants

1.

When

a user enters the password, they are redirected to the

2.

When

a user enters the password, s/he

3.

When

a user enters the password, he or

4.

When

a user enters the

5.

Atter users enter the password, they are redirected to the

6.

Atter entering the password, the user

Variant

1

is

(all

of

the user):

password, she

she

is

home

home

page.

page.

redirected to the

home

home

page.

home

page.

redirected to the

is

is

grammatically incorrect no matter

redirected to the

is

redirected to the

how much

we'd

home

page.

page.

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,

Variant 4

is

and

(they).

is

may

confuse nonnative speakers.

okay, but you must ensure that this particular user (the one entering the pass-

word) doesn't morph into he Version 5

it

later

on.

grammatically correct. After

However, the sentence

is

all,

the plural users matches the plural

pronoun

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

home

to the sentence,

ported simultaneously to the Version 6

is

your best

home

bet, basically

page, which

because

it

some

pronouns

(as in version 6)

is

readers will be trans-

skips right over the entire excruciating gender

situations, "going plural" (as in version 5)

to avoid using

users will be taken to the

all

not the intent.

is

problem and replaces the pronoun with the androgynous In

all

page. Again, literal-minded readers might imagine that

is

always

the user.

advantageous, but rewriting sentences safe.

Jul! Words > Pronouns: He, She, and They

37

Pronouns: You

I

love you.

You should

The second person

love you, too.

plural

is

a valuable

you personalizes instruction. tion, using the

It

pronoun

in technical

communication. The pronoun

sends a signal to the reader that says,

pronoun you improves an audience's

care for you. In addi-

I

attention. (Yeah, I'm talkin' to you.)

For example, compare the following variants:

1.

When

the centrifuge starts, the operator

2.

When

the centrifuge starts, you

Doesn't version 2 sound

someone

may

more personal and you

you prefer

that

must

be certain that you (the reader)

first

refer to

as

may

hear a brief cranking sound.

hear a brief cranking sound.

friendly than version

you rather than

In real

1?

of an imperative verb. (In

the verb

is

no longer

synonymous, version

1.

2.

38

fact,

wouldn't

.

really are the operator.

Imperative verbs are commands. Imperative verbs act as an implied you. in front

life,

as the operator 7 Naturally, the writer

when you

place a

pronoun

in front

Do

not place you

of an imperative,

imperative.) For example, although the following two variants are 1

sounds more natural:

Start the centrifuge.

You start the centrifuge.

Words > Pronouns: You

Pronouns:

If

and They

It

used infrequently, the pronouns

it

and they

enly use these pronouns with abandon.

used instead of

more

a

passage contains

specific

However, many readers mistak-

are benign.

becomes

It

the favorite subject for lazy passages,

noun. For example, notice

how many

times the following

it:

The carambola

is

a delicious fruit.

other places, as well.

It

is

It

is

native to Malaysia, but

very sensitive to cold weather.

It

is

it

now grows

various

in

often called "star

fruit."

The following passage reduces occurrences of it: The carambola in

is

a delicious

fruit.

Although native to Malaysia, this

various other places as well. The tree

is

fruit

very sensitive to cold weather.

now grows It

is

often

called "star fruit."

If

you look carefully

is

that writers

note that

it

at the

two passages, you might spot another problem with

sometimes change the meaning of if within

refers to a fruit.

However,

second passage, notice that the See

if

tree

you can detect the transgression

Oranges are higher

in

few sentences the fruit

—

is

which

later, it

has

become

a tree. In the

very sensitive.

in the following passage:

Vitamin C than avocados, but they have more protein.

Which has more Vitamin

C: oranges or avocados? Readers cannot

introduced two nouns and then to they.

a

— not

it,

a paragraph. In the first passage,

You must always be

tell.

A

lazy writer has

mapped only one (and we cannot determine which one)

perfectly clear

what they

refers to.

Words > Pronouns:

It

and They

39

Fluffy

One due

Phrases

of the oldest cliches in writing

most educated people

to habit,

is

to avoid old cliches

rely

on

do. These phrases are so ingrained in your writing that

them

nize

example,

as fluffy. For

concise and clearer than version

Failure to destroy Object

Q

will

Failure to destroy Object

Q

will introduce

cause the introduction of

Version 2 eliminates three words from version

TABLE

identifies a

few

common

many more

will

pop

1

4-1

at

Once you

leaks.

start noticing these wasteful

introduces (or causes)

although habitually

and

provides variety

varies

provides a detailed description of

details (v)

makes changes

changes

some

to clarification of

clarifies

to say

that

sentences,

Fluffy

is

you can simply remove the wasteful phrase that

rather than replacing

Words >

memory

leaks.

1.

as well as

some

more

now of

develops a habit of

In

is

pushes

time

spite of the fact that

is

will

Frugal

causes the introduction

that

word

Replace Wasteful Phrases with Their Frugal Equivalents

at the current

40

memory

wasteful phrases.

applies pressure

provides

a single

you.

Wasteful

in

when

you can probably no longer recog-

in the following variants, notice that version 2

1.

phrases,

writing. Unfortunately,

1:

2.

Table 4-

when

stock, fluffy phrases

it

Phrases

with that

is.

is

to say altogether

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 pay careful attention to that which I'm about to

words

are

The paradox

is

correctly, so

that although the

two

synonyms, you may not use them interchangably. Without getting into excruci-

ating grammatical terms, the rule of

•

Use which immediately

•

Do

after a

thumb

is

as follows:

comma.

not use that immediately after a

Compare

say.

comma.

the following sentences:

•

Maple trees produce a sweet sap that farmers process

•

Maple trees produce a sweet sap, which farmers process

into syrup.

into syrup.

Can and May Writers chronically interchange can and may. Table 4-2 highlights the difference.

TABLE 4-2

Can

Word

Meaning

Can

Is

versus

May Example This computer can execute

able to

(This computer

is

20

billion instructions

able to execute

20

per second.

billion instructions

per

second.)

May

Has permission or

is

to

allowed to

If

you have write permission on the directory, you

file in

it.

(If

allowed to create a

The word may

may

is

create a

file in it.)

also indicates "a possibility of." For example, in casual speech, the

of the following sentence

It

may

you have write permission on the directory, you are

meaning

perfectly clear:

ram.

Words > Commonly Confused Words

41

you should avoid using may

In formal technical prose,

confusion with the other

common meaning

to indicate possibility as

it

leads to

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

depending on whether the words are being used Tables 4-3 and 4-4 highlight their most

TABLE 4-3

When Used

common

technical

as a

words whose meanings change

noun or as

a verb.

uses in technical

and

Cutting to the chase,

scientific writing.

as a Verb

Verb

Meaning

Example

To affect

To influence

Air pressure affects acoustics. (Air pressure influ-

To effect

To bring into existence

ences acoustics.) April

showers

TABLE 4-4

When Used Meaning

Affect

Emotional appearance

The

Effect

in

psychology)

and

result or

He had

Add

outcome

a flat affect. (He

a catalyst to

flat

emotional

produce the desired

effect.

(Add

produce the desired outcome.)

word

for

its.

I'd

submit a high-priority change

Unlike every other possessive in English,

not contain an apostrophe. Table 4-5 differentiates between

TABLE 4-5

its

and

it's.

Its versus It's

Word

Meaning

Its

Possessive (something

belongs to

Example Its

coat

is

gray.

it)

A contraction

for it is

I

42

had a

It's

request to create a substitute

It's

showers

appearance.)

the English language were an engineering project,

If

flowers. (April

Example (a

a catalyst to

Its

May

flowers.)

as a Noun

Noun

term

effect

May

give birth to

Words > Commonly Confused Words

It's

a beautiful

day

in

the neighborhood.

its

does

Summary When •

of

Words

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" •

Does of

•

this

document contain jargon? Does your

this jargon? If

Are

all

the

words

your target audience clear?

Can you

is

for their

word with

a

know

the definition

do you provide

a lay audience,

replace a

own good?

target audience

more

definitions?

specific or accurate

word? •

Are the verbs strong or generic? Can you rewrite sentences containing there there

is

or

are'.

same

tense? In general, they should be.

•

Are

•

Does the same verb appear repeatedly? Vary your

•

Are any words unnecessary? Can you reduce or remove certain words?

•

Are any adjectives or adverbs unnecessary?

all

the verbs in the

a technical audience,

When

verbs.

writing a technical

you should remove most adjectives or adverbs

document

that suggest

for

mar-

keting pressure. •

Are the pronouns grammatically correct? For example, do any sentences

refer to

one

person as they 7 .

•

Does the document overuse does the reader always

•

Does the document

•

Does

the

it 7.

Are any uses of it or they ambiguous? In other words,

know which noun

refer to the reader as

document apply each word

style guide.

it

or they refers to?

you 7 .

It

should.

correctly? If in doubt, refer to a dictionary or

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

moves on

come

before and not really advancing the point until the reader

to the next

book

— any book (even an

bookstore. Yep, that's a run-on sentence. That to write. That's because you,

minds hate

fluff.

You adore

is

art history

book)

—on

the kind of sentence that

is

bored and

the shelf at the

you

are not going

my friend, are an engineer or scientist, and people with signal

and despise

logical

noise.

Sentences don't have to be long to be noisy; sentences can be as short as Napoleon but

be noisy

if

they don't say anything valuable. Similarly, sentences can be

filled

still

with good

data that gets lost in a confusing structure.

Writers generally cannot detect noise in their

own

sound or spark (unless you count the grinding of a a

good editor can detect noise

in

prose. After

all,

noisy writing emits no

frustrated reader's teeth). Fortunately,

your sentences and help you

neering process, writing effective sentences must endure

filter

it

out. Like any engi-

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

Figure 5-1

in active voice

is

in

because alpha particles (the subject) act on the nucleus (the

object).

Alpha

particles strike the nucleus.

"T

~~r

Object

Subject

FIGURE

5-1

Active-Voice Sentence

In a passive-voice sentence, the subject

is

acted

sentences, the object appears at the beginning

example, the sentence are acted

upon by

The nucleus

in Figure 5-2

in passive voice

end. For

struck by alpha particles.

Passive voice sentence

more examples.The

(Who measured Examples

final passive voice

barometric pressure?

of Active Voice

It is

hard to

example omits

a subject

say.)

and Passive Voice

Passive Voice

Active Voice

GIFs are displayed by the browser.

The browser displays

Two

Telephones connect two

parties are connected by telephones.

Barometric pressure was measured.

46

at the

because alpha particles (the subject)

i is

Table 5-1 provides a few

5-1

most passive-voice

Subject

FIGURE 5-2

TABLE

the object. In

the nucleus (the object).

Object

altogether.

is

upon by

and the subject appears

Sentences > Active Voice and Passive Voice

GIFs. parties.

The team measured barometric pressure.

Active Voice

Better

Is

Active-voice sentences offer the following compelling advantages over passive-voice sentences:

•

Active-voice sentences are usually a

•

Most readers find

•

Active-voice sentences are

•

Readers for

whom

little

active voice clearer

shorter than their passive-voice equivalents.

and more natural than passive

more powerful and

English

energetic than passive-voice sentences.

second language

a

is

voice.

will find active voice easier to

under-

stand than passive voice. (Students of English as a second language invariably learn active voice long before they learn the passive voice.)

In

summary,

Well...

How

The urge

active-voice sentences are generally superior to passive-voice ones.

Did

I

Get Here?

to write passive-voice

sentences

education. Advanced academic writing voice generates an effete

air,

connotations aside, clarity

and

is

often the by-product of a

good

often riddled with passive voice. Passive

while active voice just sounds so plebeian. Class

is

the shining gold standard of technical communications,

clarity requires active voice.

The worst misuse of passive nical

is

and

scientific writing,

whom. By tradition,

voice it is

is

the sentence that omits a subject altogether. In tech-

critical that the

reader understand

scientists often skip subjects in lab reports.

the absence of subjects

makes

lab procedures

sound

who

is

According

less subjective

doing what to

to this tradition,

and more

factual.

Thus,

temperatures are taken and slides are viewed. However, outside of Harry Potter, microscopes do not see;

humans

actor in each action.

•

the authors

•

the study

•

the lab

see through microscopes.

The following

list

It is

high time to acknowledge the

provides a few convenient actors for lab reports:

team

Sentences > Active Voice

Is

Better

47

When

Is

Passive Voice Okay?

Using passive voice once voice

when you want

in a

while

is

okay. For example, you might prefer to use passive

to stress the object rather

than the subject. For example, consider the

following active-voice sentence:

Hurricanes seldom

hit

New

York

The preceding active-voice sentence is

New

City.

is

dandy

if

the topic

is

hurricanes. However,

York City, then a passive-voice sentence such as the following might

if

the topic-

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

learn because, as In fact,

Good

your

— readers prefer skinny sentences you got

older,

to fat ones. This

a

is

tough lesson to

your teachers rewarded you for writing longer sentences.

ability to write bloated sentences

was an indicator

that

you were "educated."

engineers do not simply invent clever devices. Rather, they invent devices that can

be manufactured as cheaply as possible. Your goal as a writer information

in a

Long sentences

minimum

similar

is

— you must convey

of words.

are evil for the following reasons:

•

They

•

They

are harder to understand than short ones.

•

They

often obscure the writer's intent.

are visually intimidating.

In Table 5-2, note the relative clarity of the shorter version.

TABLE 5-2

The Long and Short

of

It

Long Version The efficiency

Short Version of

graphic images

Web

is in

browsers

displaying

in

direct correlation to the

Web browsers

display small graphics

more quickly than

big graphics

Gravitational force

depends on an

files

files.

disk resources required by the aforemen-

tioned graphic images. It

would be extremely tedious, and

cases

irrelevant, for us to

in

most

concern ourselves

mass, not on

its

object's

chemical structure.

with the atomic or molecular structure of

macroscopic ob|ects whose gravitational attraction

mass

is

is

to

be studied when the object's

essential.

Liquid precipitation on the western Iberian

peninsula

is

primarily deposited on

flat,

The

rain in

Spain

falls

mainly on the

plain.

non-

mountainous regions.

Keeping

It

Bite-Size

At Chinese restaurants, the chef rarely find knives

chops food; patrons do

not. This is

on the table at Chinese restaurants. As a

writer,

why you

will

you must become

the Chinese chef— chopping your sentences into delectable morsels so that your

readers do not have to work so hard.

Sentences > Short = Sweet

49

Causes

of

Long Sentences

rounded up the usual suspects

I've

•

jamming two or

•

using passive voice

•

being repetitious

for killing

your readers' time:

three ideas into a single sentence

•

being repetitious

•

being repetitious

•

using words or phrases that do not pull their weight

•

embedding

When

is

a

lists

that should be

sentence too long?

It is

broken into bulleted or numbered

difficult to

come up with

a

lists

magic formula.

A

12-word

sentence that minces words might be too long, while a crystal clear 20-word sentence

sometimes

just perfect. In general,

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 a few readability formulas are currently

in

is

use.

appropriate for eighth graders. Quite

Most

rely

on some mix

of the

following parameters: •

average number of words per sentence

•

average number of "hard" words per sentence

•

average number

Unfortunately,

many

of

characters or syllables per word

writers take readability quotients far too seriously, forgetting

that these formulas omit

common

sense. For example, Ernest

Hemingway wrote some of his

beautifully short sentences comprising short, simple words. Plugging

novels about bullfighting, combat, and sexual dysfunction through certain readability

formulas yields books with a readability quotient suitable

When

writing technical prose for adult professionals,

college-level readability quotient.

possible signahnoise

Aim

to

ratio.

II 50

Sentences > Causes

of

is

though, you should rarely go beyond 25 words and

Long Sentences

for fifth graders.

do not

make your message

intentionally clear.

Shoot

aim

for a

for the best

One Sentence = One Thought A

sentence should represent a single thought or idea.

thoughts, you should pick one of the following

When

a sentence holds multiple

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

Our sun should

is

between

which is powered by nuclear fusion in a process that more years or about as long as the balance is maintained fusionable material and gravity, at which time it will transition to

a yellow

last for a

readily

ideas:

dwarf

few

star,

billion

another star category.

The preceding sentence series

is

a classic

50-word run-on, slogging along

in a

marathon when

a

of short sprints would have worked better. The sentence contains four discrete

thoughts (category, power source, duration, transition), so consider the following replace-

ment containing four Our sun

is

a yellow dwarf star. Fusion

fuel to last a

enough

The

sentences:

few

billion

to fuse, our

sun

more will

powers

When

is

is

a yellow

dwarf

star,

However, I'm not wild about crete thoughts (category

comma

relegates

it

is

which

is

powered by

this solution

because

and power source).

a yellow dwarf star; fusion

is

it is

rather choppy.

To elim-

powers

now on an

fusion.

this single

sentence contains two dis-

In addition, putting the

to a second-class factoid.

Notice that the power source

atoms close

rewrite the opening as follows:

the two thoughts with a semicolon instead of a

Our sun

yellow dwarves. Our sun has enough

an improvement; however,

some of the choppiness, you might

Our sun

all

gravity can no longer keep

transition to another star category.

resulting series of sentences

inate

the

years.

power source

after

To work around these problems, connect

comma, all

as in the following

example:

yellow dwarves.

equal footing with the category.

Sentences > One Sentence = One Thought

51

Parenthetical Clauses

A

parenthetical clause

bounded by •

a pair

is

a digression,

example, or elaboration within a sentence that

commas

•

parentheses

•

dashes

For example, the following parenthetical clause

Carbon— an element

If

is

of any of the following punctuation marks:

you eliminate

in all

amino acids— can

is

a digression

easily

bounded by

a pair

of dashes:

bond with hydrogen

a parenthetical clause, the resulting sentence

must

still

make

sense. For

example, eliminating the preceding parenthetical clause leaves the following simple sentence:

Carbon can

The

easily

fiction writer

bond with hydrogen.

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

enthetical clauses are fine, but don't overuse them.

contain In

more than one

many programming

No

sentence in technical prose should

parenthetical clause.

languages,

pair of parentheses. However,

it is

fine to place a pair of parentheses inside

you should avoid

this practice in technical prose.

another

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,

should not overuse

52

commas and

dashes.

Sentences > Parenthetical Clauses

you

Summary When •

Sentences

of

reviewing your writing, ask yourself the following questions about each sentence: Is this

sentence clear? Will the target reader understand

plex for the target reader, or does

this

it? Is

sentence too com-

require knowledge that the target reader does

it

not possess? Conversely, does this sentence insult the target reader's intelligence? All other items in this checklist are subservient to clarity;

make

your primary

clarity

goal.

sentence really a sentence? (All sentences must contain a verb.)

•

Is

this

•

Is

the verb strong

and

specific,

most important word •

Does

this

or

is it

in the sentence

sentence contain an

weak and generic? The verb

— choose

embedded

numbered

a

list? If so,

to

form

•

Is

this

•

How many ideas does this sentence convey? Each idea,

•

Is

Is

or

you should

typically break

it

out

sentence in passive voice? Most sentences should be in active voice.

this sentence a

this

generally the

list.

sentence should convey exactly one

although you can connect two closely related ideas with

find a •

a bulleted

is

powerful one.

way

run-on? Does

to reduce

sentence

its

it

length, possibly

—while not

a

a

semicolon.

go yackety-yack and waste your time of day?

run-on

—

by dividing

still

it

longer than

into it

If so,

two or more sentences.

needs to be? Always search

for fat to trim. •

Does

•

Do you it? If

many when overused

this sentence contain too

clauses are okay, but

need

this sentence at all? If

the reader

would

not, erase

it.

parenthetical clauses? Occasional parenthetical

they

become

you deleted After

all,

literary

speed bumps.

this sentence,

would

the reader will never

the reader miss

know what you

removed.

Ill Sentences >

Summary

of

Sentences

53

CHAPTER

6

Paragraphs and Sections

omewhere write

in

your schooling,

good paragraphs. The

a

good English teacher probably taught you how

key, the teacher said,

was starting with

tence that introduced the paragraph and provided in

its

to

a solid topic sen-

theme. The essays you wrote

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

prose are more utilitarian,

less rigidly

every paragraph. The paragraphs in technical

structured, and generally shorter than in literary crit-

icism. In technical prose, two-sentence paragraphs are a topic sentence

is

hardly warranted.

not need to state a theme; the topic that preceded

A

section

is

a collection

it

common.

The opening sentence

In such short paragraphs,

in a technical

merely needs to introduce the topic

at

paragraph does

hand or

to build

on

it.

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

•

a

sentence

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

ing

is

of

a

word or phrase

common

is

a

•

however

•

for

•

nevertheless

•

by contrast

•

by comparison

•

in other

list

that helps ease readers into the next sentence.

The

follow-

transition terms in technical prose:

example

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

When like a

a sentence twists abruptly

in this

sentence.

from the previous sentence,

a transition

term

acts

following passage, consider the sharp turn the second sentence makes from the

Newton's formulas work remarkably are very small or are

Adding

more

a transition

moving very

term supplies

a

well.

These formulas

miserably when objects

rapidly.

warning

Newton's formulas work remarkably are very small or are

The wise writer pays

to the reader, so the following passage reads

and

forced.

well.

However, these formulas

moving very

fail

miserably

rapidly.

attention to transitions. Without transitions, paragraphs often

With well-chosen

transitions, writing

sational. Ironically, speakers in actual conversations

II, 56

fail

first:

easily:

when objects

static

much

squiggly road sign warning readers of a quick turn up ahead. For example, in the

Paragraphs and Sections > Sentence Transitions

sound

sounds more natural and conver-

do not use many

transition words.

Vocal inflections,

facial expressions,

and hand gestures

act as transitions in real-life

conversations.

how much more

In Table 6-1, notice

TABLE

6-1

The Value

fluid the passages

with transitions sound.

of Transitions

Without Transitions

With Transitions

The C compiler can process 1,000 lines of code per second. The rate slows when the

The C compiler can process 1,000 lines of code per second. However, the rate slows

host

when

is

fully

loaded.

Most commercial airplanes can cruise

at

alti-

tudes up to approximately seven miles. The

Boeing 757 cruises

at

37,000

the host

altitudes

to using transitions

theless, transitions aid clarity

fully

loaded.

up

at

to approximately seven miles

For example, the Boeing 757 cruises at

feet.

37,000

The only downside

is

Most commercial airplanes can cruise

is

that they

feet.

make sentences

a little longer.

Never-

and help engage the audience.

Conjunctions Are Not True Transitions It

is

And

tempting to here's

start a

sentence with But or And. But don't do

why— but and and

it

in

technical writing.

are conjunctions, great for intrasentence transitions but

not appropriate for intersentence transitions.

Note that starting a sentence with a conjunction

is

fine in fiction.

are not as rigid as those for technical prose. Furthermore,

(which

is

something that

conjunctions

all

fiction writers try to emulate),

is

The rules

of fiction

real-world conversations

speakers start sentences with

the time.

Although transitions are wonderful, don't

Moderation

in

feel

obligated to force

them

into every sentence.

also powerful.

Paragraphs and Sections > Sentence Transitions

57

Paragraph Length

In high school English class,

you may have been taught

to write

paragraphs to the following

formula:

•

The

•

The middle

•

The

first

final

(or topic) sentence introduces the paragraph.

three sentences are the

body of

the paragraph.

sentence summarizes the paragraph.

Consequently, every paragraph consumed roughly

When

five sentences.

writing technical prose as an adult, you might have brought along that

formula (one paragraph ~ be as long or short as

is

five sentences).

needed.

Allow

me

to liberate

you

Some paragraphs should weigh

a

—

a

same

rigid

paragraph should

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 Some writers intentionally pop in an occasional lengthy paragraph after a quick

awake. series

of short paragraphs. Your high school English teacher might not approve, but your

readers will.

Yes,

an occasional one-sentence paragraph

Beware of the rambling, massive paragraph

fine.

that just never ends.

I

graph.

A

editing such a para-

one-ton paragraph possesses an intimidating amount of girth and

such paragraphs is

is

a chore,

to divide

which

is

why many

svelte,

new para-

heft.

readers simply skip over them.

morbidly obese paragraphs into multiple

When writing for a medium

Reading

The obvious

healthy ones.

(such as newspapers) that contains very narrow columns, your

paragraphs must be exceedingly short, oftentimes only

58

When

sense that the writer hasn't figured out the right key to press to trigger a

graph,

solution

is

Paragraphs and Sections > Paragraph Length

a

sentence or two.

Paragraph Transitions

The opening sentence of a paragraph should flow

fairly naturally

from the preceding para-

graph. For example, in the following passage, notice that the opening sentence of the sec-

ond 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

Although dolphins both breathe

air

amphibians. True amphibians start their

Many

editors frown

on

have lungs, not

gills.

and swim expertly, dolphins are not life in

water prior to transitioning...

starting a paragraph with a transition term, feeling that transition

terms connect sentences, not paragraphs. For example, some editors would forbid the

fol-

lowing paragraph opening:

However, dolphins are not amphibians.

If

you cannot make

graph

in a

new or

a

paragraph flow naturally from

its

predecessor, then place that para-

different section.

Paragraphs and Sections > Paragraph Transitions

59

Sections

You should divide any document longer than so

makes

the

document

section header,

which

easier to write

is its title.

and

a

page or two into distinct sections. Doing

easier to read.

The following

are

some

Each section must begin with

guidelines for sections

a

and section

headers:

•

The opening sentence of a

section should establish the section's purpose.

•

Each section must contain

at least

tions in a •

Section

Section

on page

names

are not

body

ductory sentence in body

text

parallel.

For details on parallelism, see "Par-

and should not be treated

(or the chapter

level header, level,

many

list;

as such. For example, a

you must supply the intro-

text.

Section levels should rarely go

document

more than

title)

three levels deep, counting the

as the top level. In other words,

you should only supply two additional

levels

beyond

title

of the

that top-

of headers. At the fourth

readers lose track of the hierarchy, which leads to confusion.

Should You Number Section Headers?

Many documents provide as

a multilevel section

number

front of

in

each section name,

the following section header:

in

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 •

Engineering documents

in

when lawyers discuss the

contract.

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

audience, section numbers appear formal and intimidating, rather

"nerd crossing ahead" warning flag being waved

60

sec-

70.

section header cannot act as a valid introduction to a

•

you may not place two

is,

text.

names should be grammatically

allel Lists"

•

one sentence. That

row without intervening

Paragraphs and Sections > Sections

in their

faces.

of a lay

like a

big red

Summary When

of

Paragraphs and Sections

reviewing your writing, ask yourself the following questions about each paragraph:

•

Does each sentence flow naturally

•

Do

sentences sound choppy?

If so,

into the sentence that follows?

consider adding transition terms to the beginning

of choppy sentences. •

Do

•

Does each paragraph flow naturally into the paragraph

•

Do

•

Are any paragraphs too long? Be wary of paragraphs longer than eight sentences or so.

•

Do

any sentences

any paragraphs

Chop all

far off

When •

start

with conjunctions instead of proper transition terms?

start

lengthy paragraphs into two or three shorter ones.

the sentences in a paragraph belong together, or

do some sentences veer so

course that they belong in another paragraph?

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 •

that follows?

with transition terms? They usually should not.

Can any

section headers be

it

should?

more

specific?

For example, calling

a section

"Orcas" might not be not nearly as informative to readers as calling •

Are

all

the paragraphs in a section related, or

it

header

"Orcas: Diet."

do some paragraphs belong

in a

new

or different section?

Paragraphs and Sections >

Summary

of

Paragraphs and Sections

61

CHAPTER

7

Lists

n offbeat publication from the 1970s, The Book of Lists by David Wallechinsky and

Amy Wallace, was literally just a bunch of lists.

r

it

into a best-seller.

the titillating natively, a

list

Lists

favorable,

bulleted

•

numbered

a

big kick out of lists. After

making

their information

and made it

was

lists,

all, lists

neaten and straighten

hard to ignore. lists:

which present unordered information

lists,

which present ordered information

Inexperienced writers often confuse the two kinds of nately, the following rule

If

it

condense information and force readers to focus. Even the layout of

This chapter explores the following two kinds of •

However, readers loved

for this book's popularity? Perhaps

categories, such as the top ten sex positions or ten worst dictators. Alter-

perhaps readers just get

ragged world.

lists is

What could account

of

thumb

rearranging the elements

should be bulleted.

become confusing

If

in

a

will allow

list

you

would not

lists

and pick the wrong one. Fortu-

to pick correctly:

alter the list's

rearranging the elements

in

a

list

or incorrect, then this should be a

meaning, then the

would cause the

numbered

list

list

to

list.

Lists

63

Bulleted Lists

A

bulleted

list is

the smart alternative to an

tence contains an

A

embedded

embedded

list.

For example, the following sen-

list:

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 leted

A

list

provides far

more

tend to hide. Transforming an

list

list

into a bul-

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

many

bulleted

lists

will

lists,

so use

them

Do

liberally.

transform your prose into

Preface each item in a bulleted circle

list

with

a bullet.

A

a

not, however, overuse

them

—too

PowerPoint presentation.

bullet

is

traditionally the following filled

punctuation mark:

However, you could use another mark the

embedded

clarity:

for the bullet as long as

you do so consistently across

document.

How Many Elements Comprise

a Bulleted List?

minimum number of elements one can put in a bulleted list? Some writers say two elements and some say three. feel that two elements is the usual limit. However, you may create a one-item bulleted list in documents that have What

is

the

I

conditioned readers to expect certain kinds of information

example, suppose each page

achievements

in

of a

pharmacology

document

for a given year.

achievement, then the 1971 page should

1 64

Lists

> Bulleted

Lists

still

in

bulleted

starts with a bulleted If

list

lists.

For

enumerating

1971 produced only one significant

begin with a one-element

list.

Elements

The

text for

ment

is

Bulleted Lists

in

each element

in a bulleted list

can be just about anything, as long as each

grammatically consistent. (For more on consistency, see "Parallel

70.) In the following

example, each element of the

list is

a singular

Lists"

ele-

on page

noun:

The following are simple trigonometric functions:

List

•

sine

•

cosine

•

tangent

elements

may

example on the preceding

also be sentence fragments (as in the first

page) or complete sentences, as in the following example:

The strength

of the

two primary physical forces depends on the following:

•

Gravitational force

•

Electrical force

is

Each element of a bulleted also start with a bullet.

main

for the chy.

A

sublist

The

A main

list.

mass

proportional to the

is

two objects.

of the

proportional to the charge on the two objects.

list

can

itself

contain a sublist. Each element of a sublist must

bullet for the sublist

list

and

must be indented further than the

sublist provides

an

can also provide details about entries

effective

in the

means

main

list;

bullet

for creating a hierarfor example:

The genus Canis includes the following members: •

•

Wolves: -

Weight

-

Tail is

is

between 20 and 80 Kg.

often horizontal.

Coyotes: -

Weight

-

Tail is

is

usually less than

20

Kg.

usually down.

Lists

> Elements

in

Bulleted Lists

65

The Length Keep are

list

Each Element

elements short. In general, do not

producing

list

let list

elements exceed three sentences.

medium with very narrow columns elements down to a single sentence.

for a

lists

you should keep

When

of

list

elements get too long, consider dividing them into two or more separate

ments or possibly into example, consider

a

new

a bulleted

If

you

(such as a newspaper), then

ele-

document, complete with subheads. For

section of your

having the following structure:

list

Intro:

•

•

•

Sentence

1.

Sentence

4.

Sentence

2.

Sentence

5.

Sentence

3.

Sentence

8.

Sentence

6.

Sentence

7.

Sentence

9.

Sentence

10.

Sentence

12.

The elements

in the

Sentence

preceding

13.

list

preceding into a short bulleted

Sentence

Sentence

11.

14.

Sentence

15.

are too long to be effective as a bulleted

list

and three subheads

as follows:

Intro:

•

Sentence

1.

•

Sentence

6.

•

Sentence

12.

Subhead Sentence

1

Sentence

4.

altered.

Sentence

Sentence

2.

Sentence

3.

7.

Sentence

8.

5.

Subhead Sentence 6 altered. Sentence Sentence

9.

Sentence

10.

Sentence

11.

Subhead Sentence 12 altered. Sentence

13.

Sentence

1 66

Lists

> The Length

of

Each Element

14.

Sentence

15.

list.

Convert the

Numbered Numbered

lists

Lists

describe events that must happen in a certain order. Use

describe a sequence of steps. For example, consider the following

numbered

numbered

lists

to

list:

Perform the following steps to begin driving: Turn on the ignition.

1.

2.

Release the emergency brake.

3.

Put the car

4.

Press the accelerator gently.

in drive.

Changing the order of the elements fore, the

preceding

^QUANTUM In

a

in

list

list,

what do the

common? Each

command

numbered and

preceding

in the

must be numbered;

it

would

list

lead to car repairs. There-

cannot be bulleted.

LEAP:

the preceding

tence have is

list

of

first

words (Turn, Release,

these words

for the reader to follow.

It

is

is

Put, Press)

in

each sen-

an imperative verb, meaning that

it

a great idea to start each element of a

with an imperative verb. The imperative

will

keep your sentences short

crisp.

Each element

in a

numbered

list

should describe one and only one action. For example,

consider the following alteration:

Perform the following steps

Put the car

2.

At

first

to begin driving:

Turn on the ignition and release the emergency brake.

1.

in

drive

glance, the preceding

and press the accelerator

list

looks pretty good. However, readers are

miss details in the two-step

list

multiple actions in a single

numbered

Do

not start a numbered

element

is

list

gently.

than

in the four-step

list.

The wise

more

likely to

writer does not place

step.

element with the word then. The number prefacing each

list

an implied then.

Lists

> Numbered

Lists

67

Directions

Numbered

lists

provide the best

medium

for giving directions. For example, consider the

following directions:

To travel from 1.

my house

to the college, follow these steps:

on Occidental Blvd.

Travel 2.4 miles west

2.

Turn right on Nordic Ave.

3.

Travel 1.2 miles on Nordic Ave.

on Waverley Blvd.

4.

Turn

5.

Travel 0.6 miles.

6.

Turn right into "Parking Lot C" and find a parking spot.

left

Avoid obfuscating your directions with too many extraneous Harry's Discount a

Law and Garden, you've gone too

few helpful details to work through

some

to step 4 provides

4.

Turn

left

traffic light?)

such as

"if

you see

example, the following revision

is

missing, so look for Puddingstone

of Waverley.

in directions.

Do

not, for example, say that Waverley Blvd.

numbers produce

should we have started counting

Know your

difficult patches; for

on Waverley Blvd. The street sign

third traffic light. Ordinal

count as a

details,

Nevertheless, consider providing

useful troubleshooting information:

Bank on the corner

Avoid ordinal numbers

far."

traffic lights?

a surprising

Did

is at

the

amount of confusion. (When

the flashing yellow light at the crosswalk

Ordinal numbers also make troubleshooting

difficult.

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

As you write plete

As

it.

a

hills

and pretty red houses on the corner?

numbered

Keep each entry

list,

imagine that readers are checking off each step

you'll see later on, these

same

tions for scientific procedures.

Lists

> Directions

as they

com-

discrete.

principles will also apply

when you

are providing instruc-

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

Since

I

see

how

I

just blurted

didn't introduce the

context to help you

When

introducing a

comprehend list,

out the preceding

properly,

list

try to

the

work

list?

What

you probably have no

idea.

did those items mean? I

didn't supply

enough

1

list.

the

word following

into the sentence. For example,

consider the following beautiful introductory sentence:

The following •

oak

•

maple

is

a

list

of

deciduous hardwoods:

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 for the

list.

in

an introductory sentence, you are

Don't try to understand

this

magic

likely to

—

just accept

produce

a useful context

it.

Look Out Below Never use the word below when introducing a to the next physical page. Thus, the

sentence that introduces

it.

list

list.

might not

Lists really

have a nasty habit

of sliding

be spatially below the

Using the word following instead

of

below keeps you

safe,

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. even

1.

if

the

These are

my

list

favorite snack foods.

Lists

> Introductions

to Lists

69

Parallel Lists

Each element

ment

in a

ment

is

a

in a

list is

list

must have the same grammatical form. For example,

if

the

first ele-

elements must be singular nouns.

If

the

first ele-

complete sentence, then

element in

a

list

starts

list

in

ers

—

is

one of the

nonparallel

is

consistent

this

ways

to

We

lemon

•

lime

•

orange

The preceding

lists

elements

list

first

with a imperin a

list.

of inconsistent

does not come naturally to most writ-

amount of rephrasing. Nev-

a frustrating

is

to

pepper

with

it

in a parallel

list

must

logically

belong to that

are nonparallel

and why. (Note

that the

lists.

See

if

list.

you

answers follow the sam-

list:

lemons lime

•

orange

list is

nonparallel because the

elements are singular.

Lists

a

the

beautifully parallel. All the elements are singular nouns.

list is

•

The preceding

70

and

all

produce an amateurish document

begin with the following

•

•

lists

start

page and the next, we will consider a few parallel and nonparallel

lists.)

•

elements must

If

lists.

can determine which ple

all

said to be parallel,

amount of discipline and

surest

Beyond simple grammar, each element

On

is

called nonparallel. Creating parallel

requires a fair

it

ertheless,

elements must be complete sentences.

punctuation and case must be consistent for

which each element

elements

all

all

with an imperative verb, then

ative verb. In addition,

A

noun, then

a singular

lemon

•

lime

•

orange

> Parallel Lists

first

element

is

plural, while the other

two

The preceding

list is

with an uppercase

•

At

a

nonparallel because, unlike the

first

two elements, orange did not

start

letter.

lemon

•

lime

•

orange tree

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 starts

is

parallel. All three

elements are simple verb phrases. Each of the phrases

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

the third element does not.

To

By the way, most writers place

create a parallel a

period

the

at

first

list,

end of list elements

complete sentences, and they omit the period from

1.

in a period, but

list

consistently.

that are verb phrases or

elements that do not contain

a verb.

Insert the CD.

2.

Invoke setup.exe.

3.

You must answer the prompts.

The preceding starts

two elements end

you must use punctuation

list is

nonparallel because, unlike the

first

two elements, the third element

with a pronoun.

Capitals and Periods in List Elements

Punctuate each element of a numbered capitalize the first letter of the opening

bulleted

list,

if

the

list

list

as you would a sentence; that

is,

word and end the element with a period. For a

elements are sentences or verb phrases, supply sentence

punctuation. Otherwise, do not supply sentence punctuation.

Ill Lists

>

Parallel Lists

71

Summary When

of Lists

reviewing your writing, ask yourself the following questions about each

•

Should

•

Does

this

my

list

be bulleted or numbered?

any embedded

text contain

out into bulleted or numbered •

Should any complex

•

In a

numbered

list,

Should these embedded

Is

the

•

Is

each

first

list

Does any

element

my elements

in a

Are

text refer to

all list

numbered

list

begin with an imperative verb? (Numbered

Lists

>

list

labeled as

number

lists

to.)

1?

below or above instead of using the proper words following

elements parallel?

1 72

be broken

properly introduced? Does the introductory sentence end with a colon?

or preceding? •

lists

elements be converted into sublists?

list

do

lists?

lists?

frequently begin with an imperative, but they don't have •

list:

Summary

of Lists

CHAPTER 8

Tables

Tables are

a pleasant visual break

an untidy world into nice neat all.

When

communicating

a terrific organizational tool for

They provide

fields,

from page

after

certain kinds of data.

page of prose. They divide

appealing to the obsessive-compulsive in us

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

•

Every column contains a

•

The contents within each column

•

They

Bad

a

good caption clear,

that

summarizes the contents of the

table.

accurate header. are grammatically parallel.

are organized so that readers can easily find

tables often exhibit the following

what they

seek.

two problems:

•

The contents of cells

are so concise that they

•

The contents of cells

are so long-winded that the concise value of tables

become

cryptic. is lost.

Tables

73

Column Headers You should provide headers data

much

for every

easier to understand.

that the contents of each

column

bad or missing headers can lead sider Table 8-1,

TABLE

8-1

column

in

almost every

table.

Good

headers

are so obvious that headers are a waste of space. In fact, to

ambiguity and miscommunication. For example, con-

which contains no column headers.

Members

of the

Willow Family (without headers)

Crack Willow

Oblong lance

Europe and Asia

Peach-leaved Willow

Lance or ovate- lance

North America

Purple Willow

Parallel sides

Europe, Asia, and Africa

Weeping Willow

Lance

Asia

to linear

Although the contents of the leftmost column of Table 8-1 seem in the

make

However, writers often omit column headers, believing

fairly

obvious, the values

other two columns could have several possible meanings. Table 8-2 provides column

headers, which clarify matters considerably.

TABLE 8-2

of the

Willow Family (with headers)

Shape

Crack Willow

Oblong lance

Europe and Asia

Peach-leaved Willow

Lance or ovate-lance

North America

Purple Willow

Parallel sides

Europe, Asia, and Africa

Weeping Willow

Lance to

Asia

of

Leaves

Continent(s) of Origin

linear

When naming columns, be as specific as possible, even

if

the resulting

For example, in the previous table, although Continent

is

more

is

74

Members

Species

far less

Tables >

ambiguous.

Column Headers

name

is

not concise.

concise, Continent of Origin

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: each

•

in

•

in table footnotes

•

in

cell

column headers

Specifying the unit in each

redundant

TABLE 8-3

clutter, as in

cell

provides unambiguous data. However,

it

also generates

Table 8-3.

Specifying Units

Species

Height

Black Walnut

70-90

Pawpaw

40

Red Mulberry

25-40

in

Each

Cell

Trunk Diameter

Leaf Length

Fruit

feet

2-3

12-24 inches

1.5-2 inches

1-1.5 feet

6-12 inches

4 inches

feet

1-1.5 feet

3-5 inches

1

feet

feet

Providing footnotes reduces clutter but also reduces to multiple spots to get the full story.

When

clarity; readers

viewing Table 8-4, notice

Length

inch

must move

their eyes

how many turns your

eyes must take to locate the trunk diameter of a black walnut.

TABLE 8-4

Specifying Units

in

Table Footnotes

Species

Height 3

Trunk Diameter 3

Leaf Length

Black Walnut

70-90

2-3

12-24

1.5-2

Pawpaw

40

1-1.5

6-12

4

Red Mulberry

25-40

1-1.5

3-5

1

a.

In feet

b.

In

15

Fruit

Length

15

inches

Tables > Units of Measure

75

Specifying units in

TABLE 8-5

column headers,

Specifying Units

In

as in Table 8-5,

is

usually the best approach.

Each Column Header

Height

Trunk Diameter

Leaf Length

(in Feet)

(in Feet)

(in

Black Walnut

70-90

2-3

12-24

1.5-2

Pawpaw

40

1-1.5

6-12

4

Red Mulberry

25-40

1-1.5

3-5

1

Species

Inches)

Fruit

Length

(in Inches)

Referring to Tables In text, refer

table

to a table as the following table, the

number

1 76

preceding table, or as a specific

(Table 8-12). Don't refer to the table by

Tables > Units of Measure

its

caption (the Mulberry table).

Arrangement

of

Columns and Rows

For each table, you must pick one column to be the central organizing unit. Place this pri-

mary column accustomed

Compare

primarily because English readers are

in the leftmost position in the table,

to starting

from the

left

and moving

to the right.

Tables 8-6 and 8-7.

TABLE 8-6

North American Tree Families

Family

Species

Height

Bean

Honeylocust

70-80

Kentucky Coffee Tree

60-80

Beech

Chestnut Oak

40-60

White Oak

80-100

TABLE 8-7

(in Feet)

North Americar Tree Species i

Species

Family

Height

Chestnut Oak

Bean

40-60

Honeylocust

Beech

70-80

Kentucky Coffee Tree

Bean

60-80

White Oak

Beech

80-100

Choose Table 8-6 when readers

more

readers are

Tables

in

Tables

in

likely to

are

more

Documents Are Not Tables

in Relational

documents are not subject

be the primary

rows

in

key.

and Table 8-7 when

look up entries by species.

databases. For example, each table to

familiar with tree families

(in Feet)

The value

in

of a

a relational database table

to the

Databases

same

rules as tables in relational

a relational database

must define one column

primary key must be unique.

may

not share the

tempting to believe that the leftmost column

in

a

In

same primary

document

table

is

other words, two

key value.

It

is

a primary key,

but as Table 8-6 illustrates, the leftmost column does not have to be unique.

Tables > Arrangement of

Columns and Rows

77

In

some

cases,

two columns may appear equally qualified

to serve as the leftmost

When

this

tables.

For example, suppose you are writing a document that compares

happens, the best solution

Further suppose that others with

and

DOS.

to present the

is

some members of

same information

the audience are

more

column.

two separate

in

UNIX and DOS. UNIX and

familiar with

Instead of flipping a coin, you should provide two tables like Tables 8-8

8-9.

TABLE 8-8

DOS Commands

if

You Already

Equivalent

cd

CHDIR or CD

Is

DIR

mv

RENAME

rm

DEL

TABLE 8-9

UNIX Commands

if

You Already Know

DOS Command

Equivalent

CHDIR or CD

cd

DEL

rm

DIR

Is

RENAME

mv

Know UNIX

DOS Command

UNIX Command

DOS

UNIX Command

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.

the luxury of time, consider providing the

alphabetically

same information

in

two

tables

When

you have

—one organized

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

"Parallel Lists"

Tables

in

on page 70 describes

the importance of parallelism in

is

parallel.

To explore

TABLE 8-10

this idea,

In fact, this

lists.

also important in tables. In particular, keep the text within

concept

consider Table 8-10, in which every column

is

same

of a column

all cells

nonparallel.

Characteristics of Tree Families (nonparallel columns)

Comments

Family

Fruit

Beech

Edible nut

Needs

Maples

Double-winged

The wood

Pine

A wood cone

Produce turpentine and rosin

a wet environment. is

hard.

In the preceding table, note the following problems:

Family column, the

•

In the

•

In the Fruit

In the

Comments column,

fore, the first

TABLE

1

the

shows

8-11

isn't

a corrected, parallel

Charade ristics

entry

is

a

noun.

a sentence that starts with a verb; there-

Edible nut

Maple

Double-winged

Pine

Wood cone

tables

must be

columns. For example,

version of Table 8-10.

is

columns)

Needs fru

okay that

Comments column

a wet environment

Grows hard wood

t

Produces turpentine and rosin

parallel within it

The phrase

Comments

Beech

entries in the

plural.

is

grammatically correct.

of Tree Families (parallel

Fruit

all

first

entry ends with a period, subsequent entries must end with a period.

Family

Although

singular, but the last entry

entry consists of an adjective and a noun. To be parallel,

second and third entries should have the same form. Furthermore, since the

Produce turpentine and rosin Table 8-1

two entries are

first

first

and third entries must contain one or more adjectives followed by

the second •

column, the

columns; they do not have to be parallel between

all cells

in the

Family column are nouns, but

are verb phrases. Nevertheless,

entries throughout a table to be consistent in

number

it

is still

a

all

good idea

(singular versus plural)

for

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

example, Table 8-12 contains too

TABLE 8-12

much

each

cell.

For

cell.

Characteristics ot the Mulberry Family

Species

Fruit

Osage Orange

The

Comments

fruit

about the size

It

of a cit-

The

Mulberry

large blackberry in

fruit is similar to a

In a few cases,

color,

and

however,

humans

rarely get to taste

strip the tree of fruit the

table.

makes

most

lengthy

it.

it

fruit;

That

and other animals adore

you can bear to chop

when confronted with

set-

bows from the wood.

find the fruit irresis-

sentences. In

several

hedge forms

This tree provides exceptionally delicious

because birds

Most creatures

When

an impenetrable natural fence. Early American tlers created prized

Red

shape,

has scary-looking spikes.

tree

trees are planted close together, the

is

rus orange.

taste.

The

has a bizarre,

brainlike exterior.

more concise

text in

it

is

and

will

day before you harvest.

down, the

tree's

If

wood

excellent fences.

cells,

you can simply

cases though, lengthy

columns

edit

down

the text into

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

a

is

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 taste.

Most creatures

fruit that is similar to

These trees provide exceptionally delicious it.

That

is

If

you can bear to chop

excellent fences.

Tables >

fruit;

because birds and other animals adore

day before you harvest.

80

a large blackberry

Amount

in

shape, color, and

find the fruit irresistible.

of Text in Cells

it

however, it

and

humans

will strip

down, the

rarely get to taste

the tree of

tree's

fruit

wood makes

the

Rules

A

rule

a line in a table that

is

separates

plement of interior and exterior

TABLE 8-13

A Ruled

columns or rows. Table 8-13 contains

Comments

Fruit

Beech

Small nut

Maple

Double-winged

Needs fruit

a wet environment

Grows hard wood

warm environment

Palm

Gigantic nut

Prefers a

Pine

Wood cone

Produces turpentine and rosin

you create ruled

tables, follow these guidelines:

Use very thin

•

lines for rules.

Thick rules look clumsy. The only exception

top and bottom rules can be thicker to help

Provide

•

first

The

lines

and

a slightly thicker rule (or a

double

mark

is

that the

the table's border.

header row from the

line) to separate the

body row.

on the outside of the

interior rules. rules

com-

Table

Family

If

a full

rules.

Some

table are called exterior rules.

ruled tables omit exterior rules.

If

Those

in the

middle are called

your table does contain exterior

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

uments. 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

that contain interior rules but do not contain exterior rules.

compromise

Some

is

to render tables

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

really

answer the question, are ruled tables better than unruled tables? The answer

comes down

tables are slightly

to

form versus function. Unruled tables provide better form, while ruled

more

functional.

.

Tables > Rules

11*. 81

Shading Row

shading provides an aesthetically pleasing and highly

example, consider the shading

TABLE 8-14 1

effective alternative to rules. For

in Table 8-14.

An Example That Uses Row Shading

Comments

Family

Fruit

Beech

Edible nut

Maple

Double-winged

Needs

a wet environment

Grows hard wood

fruit

Palm

Nut

Prefers a frost-free environment

Pine

Wood cone

Produces turpentine and rosin

In the preceding table, note the following patterns,

•

The header row

which

are typical of

uses a different shading pattern than the

an option, the background color of the header row

is

shaded

tables:

body rows. When color

is

usually different from the back-

ground of the shaded body rows. •

Every other body row

•

The bottom and top rows of the

•

Other than the top and bottom rows, shaded

is

shaded.

eliminates the need for rules.

I 82

Tables > Shading

table are ruled,

which helps

tables

visually

bound

should not contain

the table.

rules.

Shading

Captions

number and

Every table needs a table

documents

are far

more

ded inside paragraphs. •

They

likely to

a useful

caption. After

all,

readers

who

are

skimming

read table captions than the table introductions embed-

Effective captions have the following characteristics:

are detailed

enough

purpose of the table but are

to explain the

still

as concise

as possible.

•

They avoid repeating

all

the

repeat at least one of the •

They

names of the

table's

columns (although you often must

column names).

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.

TABLE 8-15

What': the Best Caption for This Table? i

Species

Height of Tree

Fruit

(in Feet)

Pawpaw

40

A yellow oblong berry containing

Black Cherry

50-60

A

tiny dark-red drupe, useful in flavoring

American Persimmon

40-45

A

soft,

toxic

Suboptimal captions

for the preceding table

•

Native North American Fruit (This

•

North American

Fruit

caption

pulpy drupe

when

ripe

several seeds

and a

horrid, semi-

nightmare when unripe

would include the following: is

not precise;

Species, Heights, and Fruits (This

many

fruits are inedible.)

caption just repeats the column

names.)

A good •

caption for the preceding table

Characteristics of

Some

is

as follows:

Native North American Fruit Trees

QUANTUM LEAP Place table captions above the table. Place figure captions below the figure.

1 Tables > Captions

.

83

Summary When •

of Tables

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

•

Does each column contain

•

Do

•

Does the information

all

all

tables have a clear, accurate, helpful caption?

table? Is the leftmost •

•

a

column header? Are

all

the

column headers

in the leftmost

column

column provide

the best

way

to organize the

in alphabetical order?

columns grammatically

Is

the text within

Is

the text within certain cells too long? Should these cells be broken out into separate

parallel?

rows? Should the entire table be eliminated and replaced with prose? too long? Should the table be divided into multiple smaller tables?

I 84

clear?

numerical column headers contain suitable units of measurement?

Tables >

Summary

of

Tables

Is

the table itself

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 technical

communication engages

readers,

tographs, lucid graphs, or exotic illustrations.

themselves

—

will

deny

same people might

about pictures, while

Few people

that they like looking at pictures

learn

more from

is

usually worth

and nothing engages readers

the text, but there

—

if

Effective

pho-

being truly honest with

more than reading is

it.

like beautiful

something

text.

satisfying

True, the

and easy

text requires effort.

Wmp V >:*•

FIGURE 9-1

This picture

simply because

it

is

is

totally off topic, but

you looked

at

it

«

before you read the opening paragraph,

a picture.

Graphics

85

Time Series A time series is a The

two-dimensional graph

in

which the x-axis represents the passage of time.

,' M

/-axis could represent just about anything. For example, consider the time series in

Figure 9-2, which plots temperature in

100°-

Mytown

over a 14-day period.

I

20°.

FIGURE 9-2

I

I

I

I

I

I

I

I

1

2

3

4

5

6

7

8

Daily extremes

The preceding time •

The

in

Mytown from June

1

to

wasted,

lines at it

I

I

14

13

(a faulty graph).

is

very strong; however, starting the y-axis less useful.

Since so

much

at

The zero

space

itself).

tell

what

this represents.

The reader

is

20° intervals are too thick and strong, taking the

should be (on the data

axes are only partially labeled. Without reading the caption, you can't

cooler or

gets

little

sense of

how

warmer than normal?

1% 86

June 14

I

12

harder to get an accurate read on individual data points.

focus away from where

month •

it is

The guiding horizontal

The

I

11

y-axis spans 100 degrees, yet the actual data only spans about 50 degrees.

wastes space, squishes data, and makes the graph

•

I

10

series contains the following faults:

compulsion to normalize graphs

•

I

9

Graphics > Time Series

this data relates to the

norm. Was

this

period

Figure 9-3 improves

upon Figure

| actual

9-2.

range for this day

Q normal range for this day 90°-

Temp. (F°) 70°-

60°

2

1

4

3

6

5

8

7

10

9

12

11

14

13

June 2005 FIGURE 9-3

Daily

extremes

Mytown from June

in

1

to

June 14

Figure 9-3 does a better job of illustrating detail but the aggregate.

The

detail

(better).

still

temperatures were warmer or cooler than normal over to is

add to

summary announcing

a textual

add

a

second graph

does not help readers understand

obscures the big picture, making

— such

as the

difficult to

it

the deviation from the

in Figure 9-4

one shown

mean. By focusing on the mean, Figure 9-4 makes

it

determine whether

One norm. An

this period.

—

simple solution

is

alternate solution

on

that focuses

the daily

easy to see various cool and

warm

periods and to realize that temperatures were above normal for the period.

90° I

1

|

Temp.

70

above normal temperture

below normal temperture

o

(F°)

50" 1

I

I

I

I

I

1

2

3

4

5

6

I

7

I

8

I

9

I

10

I

I

11

I

12

13

to

June

I

14

June 2005 FIGURE 9-4

Actual versus expected

mean temperatures

in

Mytown from June

1

14.

1 i

Graphics > Time Series

87

Extra Detail

The

best graphics not only present

ested readers to dive tation

Web

Online Graphics

In

is

down

immediate information but

also provide a

way

for inter-

to a greater level of detail. Achieving this multilayered presen-

quite difficult in hard-copy graphics but relatively easy in online graphics. In a

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 the cursor over June 6, a second

Record high

93

=

window pops up

shown

in Figure 9-5.

As

a visitor rolls

to display additional information.

c

82° = Actual high at 3:57 pm

Normal mean

=

68

100

90°

HI

80 °

"

73°

=

Actual

mean

64°

=

Actual

low at 6:18 am

(

I 1

Record low

=

44

c

June 6

70°

60

50

In ri~r~rr~nT 12 4

3

FIGURE 9-5

It

5

7

Clicking on a date should provide details about that date.

would have been possible

the primary graph cluttered.

6

for a single

graph to represent

and the popup. However, the

By separating the graphs, each graph

view what they need,

as

88

Graphics > Extra Detail

in

Online Graphics

the information

shown

in

would have been busy and

stays relatively clean.

can more serious viewers.

a

all

resulting graph

Casual readers can

Before and After

In a before-and-after sequence, lay out the

two graphics side by

graphic on the

on the

left

and the

"after" graphic

for an audience that reads text after figure

shown

in

right to

left).

side,

with the "before"

you are writing

a

manual

For example, consider the before-and-

Figure 9-6.

Teddy

Wally

-|

from

right (unless

Mary

Jill

-|

-|

Teddy

Pongo

Wally

Mary

-|

Jill

Jane

,

-J,

Flo

H

Sal

FIGURE 9-6

L|

Jane

Flo

Sal

Walrus mating groups before and after introduction

Many technical communicators

of

Pongo.

mistakenly provide only the "after" picture, leaving readers

grasping for the change. The before-and-after sequence in Figure 9-7

than either picture by

FIGURE 9-7

A wine

is

more powerful

itself.

bottle, before

and

after corking.

Graphics > Before and After

89

Embedded

Callouts versus

Text

Labeling the parts of a mechanical or biological unit

To

label the parts

•

callouts

•

embedded

is

typically of great value to readers.

rely

on one of the following two mechanisms:

some distance away from

the part. For example, Figure 9-8 contains

of a figure or photograph,

labels

In a callout, the label

is

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

•

estate to

line

segment short to avoid making the reader's eyes traverse

segments

•

Don't

•

When working in

let line

cross.

a color

medium, render

the line segments in a color that contrasts

sharply with the figure.

Distal

phalanx

Middle phalanx

Proximal phalanx

\

\

FIGURE 9-8

Metacarpal

Using callouts to label bones

In

the

human

Ill 90

a lot of real

connect the label with the part.

Graphics > Callouts versus

Embedded

Text

little finger.

An embedded on the

label

is

affixed to the part

part. Therefore,

itself.

In other words, the label

part to the label. For example, Figure 9-9 contains three

FIGURE 9-9

An

Using

effective

embedded

embedded

is

stamped

directly

an embedded label has no need of a line segment to connect the

labels to identify parts of the

label

Figure 9-9, for example, the

embedded

human

labels.

digestive system.

should not disturb the reader's view of the part

embedded

enough

labels are small

that they

itself.

do not

with the outline shapes of the digestive organs, although the "Pancreas" label

is

In

interfere

awfully

close to the border.

Callouts versus

Embedded Labels

Most professional graphic parts

cannot

As

artists greatly prefer callouts

over

embedded

you are labelling are skinny, you have no choice but to use fit

embedded

a technical

communicator, I'm

communicating labels as

eyes to

labels inside the

effectively.

less

Therefore,

most professional graphic

bones of your

I

do not

artists. In

it is

lengthy line segment to a callout label

When

the

example, you

finger.

little

concerned about the sanctity of artwork than about feel

some

quite as negatively about cases,

work unnecessarily hard. For example, when

bled together like a jigsaw puzzle,

labels.

callouts. For

easier to read far, far

a

I

embedded

feel that callouts force readers'

diagram contains many parts jum-

embedded

labels than to traverse a

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

comforting words You are

a similar

mechanism

to orient technical read-

same block diagram

at the start

of each chapter in your

ers.

here.

You can use

Instead of a map, repeat the

book. In place of the magic words You are

is

the position of the blessedly

here, help readers get their

bearings by high-

lighting the relevant section of the diagram.

For example, suppose your document contains an introductory chapter followed by three chapters, entitled "Canid," "Coyote,"

Figure 9-10

on page

1

and "Gray Wolf." In

this case, consider placing

of the introductory chapter.

Gray Wolf

Coyote

Canid

FIGURE 9-10

In

The

figure you place in

Chapter

1

of the book.

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

This method of presentation picture once)

92

and highly

at the

is

beginning of the "Coyote" chapter.

simple to implement (after

effective.

Graphics > Graphics That Orient Readers

all,

you only have

to

draw the

Screenshots

One way

to

document

A screenshot

is

a graphical user interface

(GUI)

is

to take screenshots of its

of a portion of the image displayed on

a "picture"

example, Figure 9-12 shows

a screenshot.

Most

installation

a

menus.

computer monitor. For

and administration manuals

feature plenty of screenshots. In addition, online help often contains screenshots.

Display Choices

Font Family

Font Size

Anal

v

0?

10

Starting

Width

Modern

Height;

i

Helvetica

•

Courier

Units :

pi: tels

Apply Di splay Changes

j

FIGURE 9-12

Window Dimensions

v

13

A sample screenshot.

Writers import screenshots into the documentation. Then, writers provide text explaining

what the screenshot

menu

Suppose

a writer

is

readers' attention it

illustrates

or what the reader should do

when confronted with

the

in the screenshot.

documenting "Starting Window Dimensions." Good screenshots focus

on

the current topic, so Figure 9-12

is

not a great screenshot. After

all,

Window Dimensions" but also irrelevant, distracting informaand "Font Size." One way to reduce distractions is to eliminate

not only shows "Starting

tion about "Font Family"

them, leaving only the relevant portion of the screen, as shown

The screenshot

in Figure

Choices" screen)

your cake and eat

in it

9-13

is

useful only

if

the reader

knows

in Figure 9-13.

the context ("Display

which "Starting Window Dimensions" appears. too

is

to take a screenshot of the entire screen

relevant portion. For example, in Figure 9-14 a thick circle

focus on the "Starting

Window Dimensions"

makes

A

nice

way

to have

and then highlight the it

easy for the reader to

section.

Hi Graphics > Screenshots

93

Starting

Window Dimensions

Width Height Units

v

pixels

FIGURE 9-13

A subset

of the full screen.

Display Choices

Font Family

© O O O

Arial

Modern Helvetica

Courier

Apply Display Changes

I

FIGURE 9-14

If

you

The

full

)

screenshot with the relevant section highlighted.

are producing screenshots for a color

medium, render

the highlighting shape (such

as the circle in Figure 9-14) in a color that contrasts sharply with the underlying screenshot.

For example,

if

the screenshot contains a lot of blue

yellow will do a great job of catching a reader's eye.

and no If

yellow, then highlighting with

the screenshot

is

black and white

only, then render the highlight shape in red.

The Cost It

is

of Screenshots

tempting to believe that documentation

produce than documentation

built primarily

built

around screenshots

around

text. In fact,

is

cheaper

to

screenshot

more expensive to maintain because screens tend to change more accompanying text. Even a tiny change to a screen means that you must reshoot it. (Readers get nervous when a screenshot does not exactly match the menu that readers see.) The worst-case scenario is when designers change the documentation

is

frequently than the

background color or background image or font writer to reshoot every screenshot

m 94

Graphics > Screenshots

in

the book.

of every screen,

which forces the

Color Blindness

A

significant percentage of

women

of is

men

with European ancestry are color-blind.

primarily a male

phenomenon. The wise

technical

color but understands that color-coding frustrates

Contrary Instead,

to

popular

belief,

color-blind individuals

communicator

many

tiny percentage

All the subtle

do not

if

—even those categorized

you need

as color-blind

as pretty

much

the

and white.

same

color.

a single color.

— can distinguish blue from

two

to color-code a figure with only

power of

see the world in black

hues between green and red also blend into

Nearly everyone

baldness)

(like

loves the

readers.

most color-blind individuals perceive green and red

Therefore,

A

with European ancestry are also color-blind, but the condition

colors, red

red.

and blue would be

your best choices.

Many maps sea surface

provide continuous color-coding. For example, consider

temperature over

ing graphics theoretician ple suggests that a

map

a vast ocean.

1

calls

should

Such maps usually

rely

on

map showing

the

"the least-perceptible difference." This widely used princiillustrate a subtle

perceptible) change in color. For example,

if

change

in value

with a subtle (but

a sea surface temperature of 72°

orange, then a sea surface of temperature of 73° should be keyed as

of orange. This principle has great aesthetic appeal but blind. In fact,

a

a principle that a lead-

many people without

is

color blindness find

beyond it

a slightly

is

keyed as

redder shade

frustrating to the color-

difficult to distinguish close

colors.

An

alternate approach for continuous

maps (and one

that will also

work

in a

black-and-

medium such as this book) is to rely on shading instead of color. For example, the continuous map shown in Figure 9-15 shows sea surface temperatures coded with shades

white

of gray.

Edward Tufte

is

the world's leading expert

on

technical graphics. His books are a visual treat.

1,. Graphics > Color Blindness

95

Longitude West 140

135

130

125

120

30

25

Latitude

North

20 Sea Surface Temperature 77°

76°

73°

Sea surface temperatures

FIGURE 9-15

Many

75°

people find

Figure 9-16

is

it

72°

in

gray scale.

difficult to distinguish

an aesthetic

disaster,

71°

between close shades of gray. Although

most people

will find

it

easier to

understand than

Figure 9-15.

Longitude West 140

130

125

Latitude

North

77°

FIGURE 9-16

96

76°

75°

73°

Sea surface temperatures

Graphics > Color Blindness

in

72°

Sea Surface Temperature 71°

gray scale and various backgrounds.

Block Diagrams

Block diagrams typically consist of

embedded

of rectangles (or other geometric shapes) with

a set

connect the rectangles by stacking them

labels. Artists visually

to suggest a hier-

archy or by shooting arrows from one rectangle to another.

Block diagrams have become the bread-and-butter illustration of Microsoft Visio makes

it

drawing package, many block diagrams fessional-looking block diagrams

and among

single graphic

the rather inconsistent graphic

Server

engineers. a powerful

look pretty miserable. The key to creating pro-

still

consistency; you have to be consistent both within a

is

the graphics in a

all

many

draw block diagrams, but even with

rather easy to

shown

in

document. To study

this principle,

consider

Figure 9-17.

1

Server 2

Client

A

An

FIGURE 9-17

Client

inconsistent block diagram.

What's wrong with •

The

text

is

this picture? Let

set in

two

me

list

the ways:

C

different fonts. Notice that Client

than the text in other boxes. figure

B

and throughout

all

It is

a

good idea

is

set in a different font

same

to use the

font family within a

the figures in a document. If you need to

draw attention

to text, then apply italics, bold, or color. •

The

text

alignment

differs.

Some

of the

but other text (for example, Client C) vertically aligned with the top vertically centered (for •

•

same shape,

The arrows all start

start

size,

example, Server

and

aligned (for example, Client B)

to say,

some of the 1)

text

is

while other text

is

2).

all

the arrowheads in a

document should have

color.

and end from

from and end

is left

centered. Even worse,

of the box (for example, Server

The arrowheads differ. Needless the

text

is

at the

different sorts of places.

midpoint of a

line

If

possible, arrows should

segment; for example, the arrow con-

Graphics > Block Diagrams

97

necting Client 1

•

is

C and

Some

ever, if

in

graphics should typically have the same

you do mix dimensions,

ent boxes) in the

The

at least

C

is

larger than Client

A

without reason. There client

all

The

rectangles for related elements are not aligned.

server boxes should be the

left

edge of the graphic

as possible with the left

body

text

in this •

same

all

and

The

is

book

number of dimensions. How-

render related elements (for example,

or Client B;

align horizontally, as should the •

to Server

is

is

no compelling reason why

boxes should be the same

The

three client boxes should

two server boxes.

not

left

aligned.

edge of the body

are indented line

bounding Client A

is

size

size.

text

You should

on the page.

align graphics as closely

In this

indented one inch from the margin; therefore, the

The width of the

all cli-

same number of dimensions.

size of the rectangles varies

Client

•

A

of the boxes are three-dimensional and others are two-dimensional. All the

elements

•

Server 2 connects nicely, but the arrow from Client

lost in space.

book, for example,

left

edge of all figures

one inch from the margin.

segments in the rectangles thicker than the rectangle

varies.

Note that the rectangle

bounding Client

B.

Figure 9-18 corrects these problems.

Server

Client

A

FIGURE 9-18

Server 2

Client

B

Client

A consistent block diagram.

The consistency notes mentioned here

are

mere

guidelines. Clever artists can

break these rules and emerge with beautiful figures that

1 98

C

Graphics > Block Diagrams

still

sometimes

look perfectly professional.

Supplements Figures

Text That

The

text

surrounding

enhance the

a figure

should enhance the

surrounding

text

it.)

figure. (For that matter, the figure

should

This page provides a few principles regarding the prose

near a figure.

Keep

Illustrations Close to Text

Keep

illustrations physically close to the text that introduces

where the

illustration five pages later (except in a lab report

them. Don't put the relevant illustrations,

by custom, go

at

the end).

Focus Attention

The paragraph

that precedes a figure should help focus the reader's attention

that will follow. In

some

cases, the

paragraph should highlight

figure that the reader should study. For example, notice

how

a particular

on

the figure

portion of the

the following text refers to

the relevant portion of Figure 9-19.

Plug the printer cable into the parallel printer interface, which

is

shown

in

the lower

right corner of the following figure:

;•; parallel port

interface

". .

FIGURE 9-19

The

text

preceding a figure should introduce the figure.

Use Terminology Consistently Use the exact same terminology within adhere to

."A:

this subtle

the figure

and the

text

surrounding

it.

Failure to

point has caused readers immeasurable pain. For example, notice the

"parallel port interface" callout in Figure 9-19. If the

paragraph preceding the figure had

referred to this region as the "parallel interface" or the "printer interface," you'd be sur-

prised

how many

readers

would wonder what you were

referring to. Even a simple slip like

referring to this region as the "Parallel Port Interface" (in uppercase) a

would

trip

up quite

few readers.

Graphics > Text That Supplements Figures

99

Technical Photography

Digital

photography holds enormous value

for technical

communication. The following

elements have recently come together to make technical photography highly desirable: •

High-resolution cameras and storage media have become relatively inexpensive.

•

High-resolution color printing

•

High-bandwidth networks

is

inexpensive.

to transfer high-resolution

photographs have become

ubiquitous.

Most end

•

users

now

have programs that display digital photos.

Despite these advances, technical photography remains a challenging

The primary challenge technical story

you

figuring out

are telling.

how

idea.

medium

photographs

Of course, some photographs

to

to master.

enhance the

are obvious. For example,

photograph of the airplane

is

if

always a

However, suppose you are describing the aerodynamic performance of a new

airplane wing.

A

would urge you

photograph of the wing alone probably won't be to consult a digital

photography manual

speed, and so on. In the next few pages, for telling a technical story.

100

to use technical

are describing a certain airplane, displaying a

sound

I

you

is

Graphics > Technical Photography

I

all

for details

only want to focus on

a

few

that valuable.

on aperture, shutter

common

techniques

Line Art Enhances Technical Photographs

Some

people think that photography

should never mix. In order to

line art in

fact,

tell

a

more

random.

is

on juggling technique.

Instead, jugglers

ular path, at a particular height,

particulars

photography and

throw objects

is

line art

and

Jugglers

and

the

two

do not simply throw

in a particular sequence,

in a particular

along a partic-

rhythm. This entire combination of

& juggling pattern. The juggler shown

called

line art

effective story.

Please forgive a slight digression

objects at

is

you should frequently supplement technical photography with

in Figure 9-20

is

performing

a

juggling pattern called the five-ball cascade.

If

you study the

left

side of Figure 9-20, you'll quickly encounter

of relying solely on pure technical photography is

that

it is

impossible to

Horizontal motion

is

tell

which of the

the relative speed of each object.

becomes

An

for a longer period

and capture

a

arrows provide

a far clearer

way

art

B

balls are

also impossible to detect.

arrows), the direction of motion

one of the central flaws

when capturing dynamic

images.

The

flaw

going up and which are going down.

By adding

a little line art (in this case,

clearer. In fact, the length

alternative to line art

is

to

some

of the arrows suggests

open the camera shutter

blur of motion that suggests direction; however, the lineto teach the five-ball cascade.

:

m

FIGURE 9-20

Arrows help demystify a complex juggling pattern.

11 Graphics > Line Art Enhances Technical Photographs

101

Big Picture

Many movies

First,

Then

Details

begin scenes with an establishing shot that gives viewers a sense of the big

picture. For example, a certain scene begins with an establishing shot of the exterior of a castle.

Then

moves

the action

inside the castle

where we

see actors.

provides context; without the establishing shot, viewers might

The

become

establishing shot

lost.

Technical documentation that uses photography (or other graphics) should also start with

an establishing shot prior to moving details,

example, the

FIGURE 9-21

One way ple,

down

to details.

now

An

familiar Figure 9-21

is

is

a

world of wonder

in the

a reasonable establishing shot.

establishing shot of the whole scene.

to dive

down

one of the more

to detail

is

simply to magnify

common questions

a

FIGURE 9-22

Jugglers focus at the top of the juggling pattern.

Graphics > Big Picture

First,

Then

portion of the big picture. For exam-

that juggling students have

Figure 9-22 provides the correct answer.

102

There

but unless viewers understand the big picture, the details might be confusing. For

Details

is,

where do you look?

Of course,

don't

are free to

move

feel that

the

you can only display magnifications of the establishing

shot.

You

camera around, using other angles or showing other parts of the body.

For example, another

common

question from jugglers

is,

what

is

the correct stance?

Figure 9-23 helps provide the correct answer.

J FIGURE 9-23

The proper juggling stance.

Graphics > Big Picture

First,

Then

Details

103

Layout: Controlling Focus

Magic

is

an

art

way. Layout

form

2 is

an

that uses psychological principles to get an audience to look the

art

form

the right way. Learning a few basic layout techniques far

more

professional.

wrong

that uses psychological principles to get an audience to look

The primary

goal of layout

makes any document or

is

Web site look

as follows:

Get your readers to look at the thing you are trying to emphasize.

This chunk explains

how

to achieve this

primary layout

goal.

Readers Follow Pointers

When

you

first

look

at a graphic,

Instead, various visual cues guide

your eyes typically do not focus on random points.

your eyes toward a

focal point.

These visual cues are

called pointers. In illustrations, arrows are pointers. (To a lesser degree, line

out arrow heads are also pointers.) For example, what do your eyes look

segments with-

at first in

Figure 9-24?

FIGURE 9-24

My guess

Pointers guide your eyes.

is

that

you looked

at the circle

before you looked at either square. (That was the

intention of the pointers, at any rate.)

When

creating a graphic for paper or a

Web

site,

use pointers to get readers to look at the

product or technology you want to emphasize.

Eyes Are Pointers

Humans

instinctively look in the direction that other

humans

look up, the people around you will also look up. This reaction will

are looking. If you suddenly is

Figure 9-25, for example, your eyes will follow the model's eyes.

2.

Layout

is

called composition in the fine art world.

1. 104

so ingrained that

even look in the same direction that humans in photographs are looking. In

Graphics > Layout: Controlling Focus

humans

i

FIGURE 9-25

Your eyes

will

naturally look at

what the model's eyes are looking

I

at.

Readers Are Attracted to Discontinuities Readers focus on any discontinuities in color, shading, or contrast. For example, Figure 9-26, your eyes will probably focus

on the shaded

circle first,

even though

in it is

not

in the center of the figure.

FIGURE 9-26

Humans as the

Changes

in

shading also catch your eye.

focus sharply on abrupt changes in color.

Web, render the object you are trying

with the background. For example,

background

in yellow.

An

way

alternate

you want

to

a beeline for

to use color

is

if

you

to

When working in

emphasize

are trying to

a color

medium

such

in a color that contrasts strongly

emphasize

a

blue object, put the

to render the entire setting in grayscale except for the object

emphasize. Render that object in a sharp color. Your readers' eyes will make it.

Graphics > Layout: Controlling Focus

105

Layout: Keeping Eyes on the Page

The second

goal" of layout

is

as follows:

Keep your readers' eyes focused on the page.

The preceding

goal probably strikes

you

as a bit odd. After

you are reading

all, if

a

book,

why would you want to focus your gaze outside the page? For that matter, if you are gazing at a Web page, why would you suddenly turn your attention to another program? Well, let's start with the extreme case shown in Figure 9-27.

FIGURE 9-27

Your eyes follow this pointer right

off

the page.

This arrow carries your gaze right off the page. Figure 9-27 would artists faint

in Figure

9-28 take your

FIGURE 9-28

3.

106

Some

from pain. Remember that human eyes are

What

graphic

is

own

professional layout

powerful pointer; the model's eyes

it

isn't

eyes right off the page.

she looking at? You can't

artists

make

a

would describe

tell,

this as the

but clearly,

on

this |

primary goal rather than the secondary

Graphics > Layout: Keeping Eyes on the Page

goal.

Layout: White Space

White space

is

the part of a printed page that contains

white space

ally white,

do not contain

A

ink. In a

background color

the

literally refers to

Web

key principle of layout

White space

The

is

page, the white space

is

is

is

usu-

is

Web

the

background

page are

still

color.

Thus, even

termed white

if

space.

as follows:

good.

corollary to this principle

Clutter

blocks of the

is teal, teal

no information. Since paper

the white sections of the page, or the sections that

is

as follows:

bad.

In a technical manual, readers love white space.

into a small space

Cramming

makes readers nervous. White space

is

an

too

much

island.

visual information

White space

is

a place

for the reader to rest before attacking the next topic.

When

creating illustrations, always consider white space. For example, consider

Figure 9-29, which suffers from a serious white space deficit.

DBMS

JDBC

(Database Manage-

FIGURE 9-29

•

J2FE (Java 2 Enterprise Edition) Application Server

Not enough white space.

looking

Just

(Java Database

Connector) Driver

ment System)

at

Figure 9-29 makes

White space

is

me

feel

claustrophobic. This figure's sins are as follows:

missing above the top of the figure and below

its

caption. Notice

how

scrunched the entire figure appears. Because of the absence of white space, some readers might not even notice the existence of the figure at •

The

artist

and hard •

The

has placed too to read. Notice

all.

much text inside the three rectangles; the text how the text bumps up against the rectangles.

is

cluttered

rectangles are too close to each other.

Figure 9-30 exaggerates white space the rectangles has been stripped figure should

somewhat

down

to

make

a point.

Notice that the text inside

to the essentials. (Text preceding or following this

expand the acronyms.)

Graphics > Layout: White Space

107

DBMS

JDBC

Driver

J2EE Application Server

FIGURE 9-30

Note

that

because

Rearranging the elements to enhance white space.

it is

not always appropriate to recast a horizontal drawing as a vertical drawing

a vertical

drawing can imply

a hierarchy.

QUANTUM LEAP Many people center graphics halfway between

the

left

margin and the

However, most graphic artists prefer to lay graphics out flush with the their captions.

108

Graphics > Layout: White Space

right margin. left

edge

of

Summary When

of

Graphics

reviewing graphics in your document or

Web

site,

ask yourself the following

questions:

•

Does the

illustration

supplement the body

text?

illustration help to explain the illustration?

Does the body

Does the body

text

surrounding the

text use the

same termi-

nology as labels inside the illustration? •

Does the is

just

illustration contain a caption?

below the

illustration.

By convention, the caption

for an illustration

Does the caption accurately convey the purpose of the

illustration? •

If

the illustration contains labels, are the labels consistent? For example, a single illus-

tration should not

mix

callouts

and embedded

labels. Is the font consistent

through-

out the illustration? •

Is

the illustration working too hard to

illustration tion,

is

a little like a

you should divide

it

paragraph

cram

in as

—when

it

much

starts to

information as possible?

An

informa-

in two.

graph, are both axes clearly labeled? Are the units clearly labeled?

•

If this is a

•

Have you optimized the presentation of your graphics by providing

Do

much

contain too

pointers push readers' eyes off the page? Does the page contain

space, or does

it

a

proper layout?

enough white

look cluttered?

Graphics >

Summary

of

Graphics

109

CHAPTER

10

Professional Secrets

T

his chapter teaches the tricks

of the trade.

It

takes

you well beyond the basics and

squarely onto the turf of professional technical and science writers. Mastering these

techniques will

In this chapter,

you

bump

your writing up from merely adequate

will learn the following techniques:

•

building explanations for technical readers

•

building examples in a variety of ways

documents

question-and-answer format

•

creating

•

describing the same principle in multiple ways

•

picking the proper tone

•

varying the pace

•

creating footnotes

What

Is

Good

Writing

The best description

in

and sidebars

Anyway? of

good writing that

I've

ever heard didn't

writer but from an experienced engineering manager.

on

my

staff

That one

and said that he

line

has stuck

counterintuitive,

in

"really

my head

knew how for

many

to

it,

in

doing

just like a

it

good

tell

all,

come from

He pointed a

good

it

the trick

so that your audience

will

to

one

a fellow

of the writers

story."

years because

and completely accurate. After

something clearly but

and remember

to truly superb.

is

is

simple,

not just

in

explaining

actually want to read

it

story.

Professional Secrets

111

Explanations of Formula-Based Rules

Science writers must frequently explain rules or principles, often those based on algebraic

formulas. To explain a rule or principle to a technical audience, consider using the following algorithm:

1.

State the rule or principle formally.

2.

Supply the relevant mathematical formula.

3.

State the rule or principle casually.

4.

Provide an example that shows the rule in action.

5.

Describe special cases or limitations with the formula.

6.

Provide a succession of examples that use the formula.

To explain

a rule or principle to a lay audience, focus

members of a

lay

on

steps 3, 4,

and possibly

5.

Most

audience will run screaming from anything that involves algebraic

formulas.

The following page

uses Steps

1

through 5 of the preceding algorithm to explain the rules

of gravitational force. The members of the target audience are college freshmen taking an introductory physics course. As always, the wise writer focuses on the interests of the audience; college freshmen might enjoy a hint of romantic attraction

thrown

in

with gravita-

tional attraction.

Note that

this

is

ment. Following ples,

a relatively brief

explanation for a topic that requires a

this initial description, a

good writer would provide

technical readers learn

112

fuller treat-

of exam-

each one building on the previous one and getting gradually more sophisticated. Most

more through good, mathematically based examples than through

prose.

Ill

much

a succession

.

Professional Secrets > Explanations of Formula-Based Rules

Gravitational Force (an

example

of

an explanation)

The gravitational force between any two objects their

two masses and

them. The formula

for

is

is

proportional to the product of

inversely proportional to the square of the distance

between

determining the gravitational force between any two objects

is

as follows: (G)(M 1 )(M 2 )/R

=

F

2

where:

expressed

•

F is force, typically

•

G

is

•

Mj

and M 2 are the mass

•

R is

in

N.

the gravitational constant, which of

6.673 x 10" 11 m 3 /kg 2 s.

is

two objects, expressed

in kg.

the distance between the two objects, expressed

in

m.

more massive objects exert a stronger tug on each other than light objects. Thus, two stars pull more strongly at each other than two paperclips. In addition, gravitational force depends heavily on the distance between As the formula

indicates,

the two objects. Since this

is

distance between two objects

an inverse-squared proportionality, doubling the

decrease the gravitational force between them by a

will

factor of four.

Gravitational force describes the tug that

example,

at this very instant, the stapler

each other

two tempestuous

like

gravitational force their spot

the

is

much

of

ruler

other. For

on your desk are lunging towards

lovers. Unfortunately for this

unlucky

pair, their

smaller than the force of friction that holds them glued to

on the desk. However,

vacuum

any two objects exert on each and

if

you were

to transport this star-crossed pair into

space and place them a few meters apart, they would

toward each other, eventually clinging together for

start

moving

eternity.

Example

A photocopier machine having 18 kg are 2.5

m

apart.

What

a

mass

of 125 kg

gravitational force

and a laser printer having a mass

of

do they exert on each other?

Given: G

6.673 x 10" 11 m 3 /kg 2 s

=

Mj

=

125

=

18

M2

kg kg

R

=

2.5 m

F

=

G^MM^/R

F

=

F

=

When

2

11 (6.673 x 10" m 3 /kg 2 s)(125 2.4 x 1G- 8 N

kg) (18

kg)/(2.5 m) 2

objects are extremely small— down to the subatomic size— the preceding

gravitational force formula no longer applies.

In fact,

a different set of forces takes

over.

Professional Secrets > Explanations of Formula-Based Rules

113

Examples Good

descriptions require

abstract for readers.

good examples; descriptions without examples

Adding examples renders the

abstract

more

are often too

concrete. For example,

consider the following wholly accurate (but colorless) description for lay readers:

The pressure

of a

gas

What could be harder far better to use

is

proportional to

its

temperature.

to visualize than an invisible gas?

When

writing for lay readers,

it is

examples that describe everyday phenomenon rather than laboratory or

mathematical phenomenon. To help readers visualize

this principle,

expand the descrip-

tion with a familiar example, such as the following:

The pressure

of a

gas

is

proportional to

Its

temperature. For example, have you ever

how flat your tires can look on a frosty morning? As the day heats up though, those same tires begin to look robust again, even if you don't pump more air into them. The gas pressure increases because the sun raises the temperature of the air noticed

inside the

tire.

Did you notice that the example started with

a rhetorical question? Rhetorical

questions

help suck in readers far better than simple statements.

The example has ...have

a casual, personalized feel to

you ever

it.

something obscure or

Examples must be appropriate ate for

most readers

in

However,

this

is

a

phenomenon

within his or her expe-

rare.

to the target audience.

The preceding example

is

appropri-

North America and Europe since such readers usually own some

vehicle with tires (bike or car) tions.

is telling:

noticed...

Referring to the reader as you suggests that this rience, not

The following phrase

and experience appreciable diurnal temperature

example probably

isn't

meaningful to readers

fluctua-

in equatorial climates

since they typically won't experience tire deflations in the morning.

Note that some serious technical journals do not permit the use of you

114

Professional Secrets > Examples

in

examples.

Examples by Metaphor Metaphors ples. In a

are not just a literary device

— they can

also

come

in

handy

in technical

metaphoric example, instead of providing an example of a phenomenon

you compare the phenomenon

to

at

examwork,

something analogous. For example, consider the follow-

ing metaphoric example:

Client-Server Architectures (a metaphoric example)

Many modern computer systems

rely

on a client-server architecture. A client-server

architecture consists of the following two kinds of components:

which are components that make requests

•

clients,

•

servers, which are

components

that

fulfill

those requests

Since clients and servers are typically on different machines, the requests and

responses must flow through a network. Operations within a typical restaurant are similar to a client-server architecture. The

hungry customers are

clients. Like all clients, the

customers make requests.

Pad Thai, please.") The chefs are servers, responding

sumptuous

to client requests

("I'd like

by preparing

plates of noodles. Waiters take on the role of the network, shuttling

requests and responses between clients and servers. Client-server architectures

bog down when too many

period. Suddenly, instead of a server responding

respond all.

sit

for ten

seconds or more.

In fact,

You've probably seen this happen

down around the same

in

in

clients

make

requests

in

a short

two seconds, the server might not

the server might be too busy to respond at

a busy restaurant.

time, the wait for food

When

becomes

too

many customers

intolerable. At

such times,

the waiter might even apologize profusely, saying that the chef lost your order.

The preceding metaphor cases,

fits like

In fact, the analogy can even apply to special

a glove.

such as the overloaded servers in the

(restaurant operations)

is

final

paragraph. The analogous

phenomenon

familiar to everyone in the audience. Finally, the analogy

is

kind

of fun, since most readers enjoy going to Thai restaurants.

1.

Well, almost. Since waiters often introduce themselves by saying "Hi,

server tonight," this analogy could confuse

some

my name

is

Fred,

and

I'll

he your

readers.

Professional Secrets > Examples by Metaphor

115

Examples

Just as

many

Programming Documentation

for

umentation about programming.

In other words,

programs and only read the prose code the examples

good examples •

many

readers skip over text to look at pictures,

tions of principles in order to get to examples. This

for

first

as a last resort.

and then write the

text

programming manuals

Start with a very simple example.

is

readers skip over dry recita-

particularly true

programmers often

When

when

writing doc-

gravitate to

example

programming manual,

writing a

around the examples. The keys

producing

to

are as follows:

Then, gradually

layer

on complexity

in

subsequent

examples. •

Do

not assume that your audience will always read the prose preceding or following

the example. Provide meaningful

comments within

the code

itself.

Do

not, however,

overwhelm the code with too many comments; don't comment the obvious. •

Provide crystal-clear variable and function names. For example, naming a variable

NumberOfRecordsProcessed helps the reader a •

Format the code

lot

more than naming

for clarity. Place blank lines before

and

it

X.

after discrete blocks

of code.

Don't forget to indent code properly.

To

illustrate these principles, let's

ming language named

Example

1:

Hello World

In 1971, Brian

mark

consider a sequence of examples for a fictitious program-

Fenster.

Kernighan and Dennis Ritchie, two researchers

technical book,

The

C Programming Language. The book

example that wrote the phrase Hello World

become known

as Hello

often

wrote

opened with

to the terminal. Since that time,

ming manuals have begun with an ultrasimple example, Hello World to the terminal. Such examples

at Bell Labs,

one

a

good program-

that writes the phrase

—whether they write Hello World or not — have

World examples.

// This example writes the phrase "Hello World." to your terminal, program HelloWorld // Every program needs a name

routine start // A routine named start must appear in every program, begin

WriteToTerminal ("Hello World. \n")

// The \n is

a

newline character,

end

116

Professional Secrets > Examples for

a land-

very short

Programming Documentation

Example

2:

Simple Variables

After getting the Hello World example to run, readers will want to see a slightly

plex example. For example, the following

program

creates

and uses

// This example demonstrates how to declare a variable, // and then write its value.

program Oecl

a

more com-

a simple variable:

assign

a

value to it,

reAssignAndWriteAn Integer

routine start begin // Declare an integer variable named tacos. integer tacos // Assign a value to this integer variable,

tacos

=

3

// Write tacos' value (3) to the terminal. Notice that we don't put double // quotes around tacos. If we did, the program would write the word // "tacos"

instead of the value 3.

WriteToTerminal (tacos) WriteToTerminal ('\n') end

Notice the copious

comments throughout

the preceding example. Like an experienced ser-

geant leading his troops safely through a mine readers of a potential pitfall ("..

Example

3: Input

Since the

first

want

field,

the final block of

comments warns

don't put double quotes around tacos.").

two examples showed how

know how

to

.

to read information.

to write information, the audience

The

third

might now

example provides an answer:

// This example demonstrates how to read data that the user types,

program ReadAnlnteger routine start begin

integer tacos

WriteToTerminal ("How many tacos would you like?") // Prompt the user. ReadValueFromKeyboard(tacos) // Read the value that the user enters.

WriteToTerminal (tacos

+

'\n')

// Echo the value that the user entered,

end

Professional Secrets > Examples for

Programming Documentation

117

Question-and-Answer Format

Question-and-Answer (Q-and-A) format

is

exactly

what

sounds

it

like

—

a collection

of

questions and their answers.

Q-and-A format by

is

a

compelling choice when your audience has

and

their nature, love to solve riddles

it

right. Technical

and-A format

is

refreshing break

Despite

its

also a

then read the answer to see

in a header,

documentation becomes

good choice

a scientific bent. Scientists,

be challenged with tough questions. Scientists

attempt to answer the question posed

will often

they got

to

a sort

of subconscious

many

for a lay audience since

if

game show. Q-

readers find this style a

from standard prose.

charm, readers quickly

written completely in

Q-and-A

of Q-and-A format. Very few long documents are

tire

style;

more

often, this style

is

reserved for brief documents

or for individual chapters in a lengthy book. Variety generally pleases intelligent readers, so a single

The keys •

Q-and-A chapter

to

in a lengthy

good Q-and-A documents

Imagine that you are writing vides bit

all

book provides

all

two characters

the answers

As

— one who

is

come from another

slightly naive pro-

character

who

in a play, let the

and somewhat

For example, you can end an answer by introducing

Write casually

Keep your answers

casual.

a

new term and then

use the

new term means.

—don't confuse Q-and-A format with

•

•

rarely

short. Don't turn

consider an approach other than

How Does Q-and-A Format Differ from

a lab report.

your dialog into a monolog. Answers should

go over a paragraph and should never exceed

lengthy, readers will forget the question. If

many

a page. If

an answer

is

too

of your answers are too long, then

Q-and-A format.

a

FAQ?

A FAQ answers frequently asked questions about a certain product or technology. FAQs are similar to a standard Q-and-A document. However, a FAQ is not meant to be read sequentially— it is just a list of questions that readers can access in random By contrast, Q-and-A documents are written

to be read linearly (from start to

finish).

i 118

a

answer to a question flow naturally into the following question.

next question to ask what the

order.

is

of a know-it-all. Allow the two characters to take on different personalities. As in

a play, try to keep the dialog conversational •

change of pace.

are as follows:

a play for

the questions, while

a clever

Professional Secrets > Question-and-Answer Format

Question-and-Answer Format (example)

The following example nophobic

to explain a firewall product

lay readers greatly prefer the

manual. The

tional technical

tone

Q-and-A format

uses

Most

lay readers.

Q-and-A format

style is highly conversational

and easy

aimed

to a

to read.

at tech-

more

tradi-

Note that

this

generally inappropriate for a serious technical audience.

is

InfiGuard (an example of Q-and-A format)

This

document explains how the

Why do need

a firewall?

I

A

you from individuals trying to harm your PC or

firewall protects

Why would someone want

But I'm a good person.

We know

InfiGuard Firewall protects your PC.

you're a good person.

We

only

to

steal data

from

it.

damage my PC?

sell to

good people. However, there are some

very bad people on the Internet.

What could they do

to

my PC?

Unspeakable things. They could render your PC completely unusable.

mess up your PC so

badly, you'd wish

it

were dead.

take note whenever you went to a questionable

How does

A

a firewall protect

Or,

Web

Or,

they could

they could spy on you and

site.

my PC?

firewall only lets trusted

people and organizations gain access to your

to certain benign portions of your PC, at that).

The

firewall prevents

PC (and

only

any

untrustworthy people and organizations from gaining access to your PC.

How does the The

firewall

firewall will

Do need a degree I

know who

to trust?

ask you. computer science to answer

in

No. The firewall asks you

in

question such as, "Dexco Unlimited suspicious. Should

Is it

really that

About

95%

I

its

questions?

plain English. For example, the firewall is

trying to install a

file

might ask you a

on your system.

prevent Dexco Unlimited from installing the

file?

It

looks

(Yes or No.)"

easy?

of the

questions really are just that easy, A few questions are more

complex, but the InfiGuard Firewall

will

recommend an answer

for the really

tough

ones.

Professional Secrets > Question-and-Answer Format (example)

119

Other Words

In

We've as

if

had bad teachers

all

who

could only explain things in one highly specific way, almost

they were teaching the class from a script. For example, consider the following class-

room

dialog:

Teacher: Cells contain units called organelles. Student:

I

don't understand.

Teacher: Cells contain units called organelles. Student: [Realizes teacher pointless.] Yes,

The

best teachers

I

worthless and that further questions would be

is

see.

know

that different students latch

on

to different kinds of explanations;

therefore, great teachers explain each key concept in a variety of ways. Unfortunately,

writers explain key concepts in only

readers are forced to reread the

The phrase example

is

in other

words

sufficient for

is

same

passage,

a valuable tool.

many

Hydras reproduce asexually. it

one way. With only

many

a single explanation, befuddled

which doesn't

Although the

get

first

them anywhere.

sentence in the following

readers, the second sentence should handle any stragglers:

In

other words, a single hydra can reproduce

all

by

itself;

does not require a partner.

Although

in other

The phrase

that

is

words

is

a

handy phrase, not

all

second-chance explanations require

can also be quite helpful, as in the following example:

Sexual reproduction generates more diverse offspring than asexual reproduction; that is,

offspring of sexual reproduction differ from their parents, while offspring of

asexual reproduction are genetically identical to their single parent.

lilt 120

...

Professional Secrets >

In

Other Words

it.

Tone

Tone

is

to writing

what

mood

is

to a social gathering.

unemotional, and businesslike, while others are

light

although the tone of most technical documents

is

would

prefer a lighter tone.

The

trick

Some and

social gatherings are serious,

filled

to assess your audience's

is

with laughter. Similarly,

serious, there are times

mood and

when

readers

figure out

what

kind of party to throw.

For example, consider the following troubleshooting instructions from

camera manual written with The most is

common

cause

a

consumer

digital

a serious tone:

of

perceived failure

in

the Carambola

5000

digital

camera

an uncharged battery. Batteries not only discharge rather rapidly with use but also

discharge during periods of disuse.

The preceding passage

features good, short, active-voice sentences; however, the formal

tone

as if the writer

off-putting.

is

Remember

—

this

It is

a

is

manual

for

ual for cardiologists learning to

showed up

at

mardi-gras wearing a three-piece

consumers taking pictures of their pet poodle, not perform bypass surgery. Flipping the passage

a

suit.

man-

to a lighter

tone yields the following:

We

Carambola Industries are concerned with our self-esteem and want

at

to

do

everything possible to prevent the following dialog: You:

My Carambola 5000

Us: [Concerned.]

You:

Us:

It

If

must

be.

I

Is

is

broken!

the battery charged?

charged

it

up and haven't used the camera

for six

the camera hasn't been used for six months, then the battery

months. isn't

charged.

That battery can only hold a charge for about three months. You: So, the

camera

Us: [Wiping tears

Most people only

isn't

broken?

away] No

sir.

learn to write in

It

is

likely in fine order.

one

tone. Experienced writers master multiple tones

among them as required. Although a single document is generally written in a single tone, you may need to shift tones periodically. For example, even a light-toned consumer manual should turn deadly serious when discussing safety issues. and

shift

Professional Secrets > Tone

121

Pace

Pace

is

the speed at which a

Pace

ual.

What

is

pace

game. The

document presents information. Given

manual covers the material

to present, a fast-paced

in

a certain set of facts

fewer pages than a slow-paced

man-

information density.

is

best? Mastering pace in writing

trick

is

in

knowing when

to slow

is a little

like

mastering

down and when

ing, intelligent readers prefer a fast pace. This

book, for example,

pace. However, even highly intelligent readers prefer a slow pace

highly complex or confusing. Thus, this

a car-racing

video

to speed up. Generally speakis

written at a rather

when

fast

learning something

book slows down occasionally

to bathe in the

tougher concepts. To slow things down, consider explaining the same concept multiple

ways or providing multiple examples.

Many

writers change pace just for the sake of change. If

done

well,

changing pace helps

engage your audience. The following techniques are helpful for varying pace: •

Mix the

in a short

paragraph between a couple of long ones. Keeping each paragraph

same length

is

like delivering a

speech in a monotone

—

you'll just

put your audi-

ence to sleep. •

Break up long strings of paragraphs with some bulleted and numbered

•

Sprinkle tables throughout a document; don't

•

Break up long blocks of

•

Use sidebars.

text

lists.

clump them.

with an occasional figure or photo.

What Are Sidebars? These shaded blocks are

common

in

of text sprinkled

throughout the book are called sidebars. They

newspapers and magazines but somewhat

documentation. That's too the distinct shading

in

bad— readers'

eyes

feel

rarer in technical

an almost gravitational

pull

toward

sidebars.

Authors use sidebars for interesting digressions that would otherwise become non sequiturs

make

122

if

placed

in

a traditional paragraph.

sure they have your attention

Professional Secrets > Pace

Some

authors also use them just to

when making an important

point.

Footnotes and Other Digressions

Sigmund

Freud," a prolific and superb science writer

who had

-

with fascinating examples, loved footnotes. Footnotes

down

notes

the

at

bottom

forgiven since footnotes were

was

a writer easily

pades,

text in footnotes

some He can be

that

a

century ago. Plus, he linguistic esca-

writers use considerably fewer footnotes than those of Freud's time. In fact,

them from documents

uate textbooks and only occasionally see

some academic

Many modern

journals

still

altogether.

them

of

it

disappeared

ingest information as rapidly as possible.

up from footnotes

them

in

many

undergrad-

commercial or corporate manuals. 5 How6

—

a victim

So,

what happened

to all the

of the incessant need to present

The remaining

really cool stuff

has crawled

into sidebars.

book has hounded you

for anecdotes

rarely see

require citation footnotes or endnotes.

which Freud generally used them.

really cool stuff? In fact, a lot

Since this

in

You

readers associate footnotes with "boring academic stuff" rather than with

the "really cool stuff" for

and

works about

whisked away into digressions, intriguing anecdotes, and

editors have banished

ever,

them so much

than in standard paragraphs.

the rage in scholarly

all

engaging audiences

of which could find a satisfying release in footnotes.

all

Modern

a gift for

of course, those tiny numbered

(the foot) of the page. Freud loved

more

pages actually contained

are,

to be concise,

you might wonder

if

there

and curious digressions, or whether such information should

By way of explanation, suppose you must

travel

from Florin

to Guilder.

a place

7

- ~ \

Florin

is still

stay repressed.

direct route

scenic route

_^#Guilder FIGURE 10-1

What

is

the best route from Florin to Guilder?

2.

Freud, the founder of psychoanalysis, lived from 1856 to 1939.

3.

Of course,

4.

He spoke

5.

This manual, for example, uses noncitation footnotes, primarily as an outlet for weak jokes.

6.

Endnotes are

than 7.

at

it is

pretty easy to fascinate an audience

eight languages

when you

are writing about sex.

and could always come up with the perfect adage

just like footnotes except that they

appear

in a

clump

at

in

one of them.

the end of a

document

rather

the bottom of the source page.

You might recognize

Goldman took

these as the

these pretty

two featured countries

names from the two terms

for

in

William Goldman's novel The Princess Bride.

pre-Euro Dutch currency.

Hi Professional Secrets > Footnotes and Other Digressions

123

The map

you can either take the

The wise

hurried and the scenic route

when time

route

124

in Figure 10-1 suggests that

scenic (but digressive) route.

is

always

direct (concise) route or the

writer allows the reader to take the direct route

permits.

From

when

a pedagogical perspective, the scenic

more memorable.

Professional Secrets > Footnotes and Other Digressions

Beyond the Obvious Good

technical writing doesn't take the easy

nical writing always seeks to

tell

the

whole

way out by just

good

stating the obvious;

tech-

For example, consider the following

story.

description from a photo-editing software manual:

Edit -> Convert -> ColorToGrayScale

The ColorToGrayScale menu option converts

Note that the target audience pro photographers

who

a color

image

to grayscale.

for the preceding passage consists of professional

are already quite knowledgeable about

photography. The preceding description anything that they don't already know.

is

accurate, but

Compare

it

many

and semi-

aspects of digital

doesn't really

tell

these readers

the previous description to the following:

Edit -> Convert -> ColorToGrayScale

The ColorToGrayScale menu option converts precisely, the function in

which

R, G,

maps each

and B are

all

a color

screen pixel from

identical,

which

is

image to grayscale, More

its

current

always a shade

RGB

value to a value

of gray.

The

resulting

black-and-white photo can display up to 256 different shades of gray ranging from

pure black to pure white to everything

The conversion algorithm

relies

and a bright red

bright blue ball

in

between.

on the intensity ball of

of

each color

equal intensity

will

pixel. For

example, a

look identical

when

converted using this algorithm.

The conversion algorithm

is

not the

same one

that

in

slightly brighter

(more white) images than most

and white mode. and the

As you can

digital

We

tion

camera algorithm tends

see, the fuller

fuller

cameras use when

digital

cameras shooting

in

black

to look better

when

printed.

explanation attempts to answer the questions that the target audi-

explanation could go a

would show

digital

have found that our algorithm tends to look better on screen,

ence would have. The earlier one-line explanation

Even the

most

black and white mode. Our conversion algorithm tends to produce

taking a picture

different

lot further.

sample images

in color

is

worthless.

For example, a more complete explana-

and then converted

to black

and white,

along with explanations.

IS

Professional Secrets

> Beyond the Obvious

125

Precision Descriptions

Many

of the comic books that

dence

art school.

you wanted

to be an artist,

committee.

If

read as a kid contained an advertisement for a correspon-

you drew

a picture

a picture

name was Winky.

of a deer. His

of Winky and mailed

you could draw Winky accurately, then you had the

famous comic book I

I

The advertisement showed

it

If

to the admissions

right stuff to

become

a

artist.

believe that ads for a correspondance technical writing school should also feature Winky.

Except, instead of drawing Winky, you verbal picture so perfectly that ture

Winky

would describe him

in

someone who had never seen

words.

If

you could paint

a

a cute wittle deer could pic-

exactwy, then you would be granted admission. After

all,

good

technical

and

scientific writing often requires precise verbal descriptions.

Do you

have what

School?

If

you

feel

takes to enroll in the

it

Famous Technical Writer Correspondence

good about your chances, take out

a

sharpened

QWERTY keyboard and

describe exactly what you see in Figure 10-2. Your explanation should be so

someone with looking

at.

FIGURE 10-2

a scientific

(No

fair

looking

The admissions

at

the next page until you have completed your

test.

L 126

good

that

or technical background could understand exactly what you are

Professional Secrets > Precision Descriptions

test.)

The following

is

description of Figure 10-2:

a possible

The figure contains two rectangles, referred •

the outer rectangle

•

the inner rectangle

The outer rectangle wide by

1

inch

to as follows:

is

4 inches wide by 2 inches

is

completely inside the outer rectangle. The top and bottom

tall;

the inner rectangle

is

2 inches

tall.

The inner rectangle

sides of the inner rectangle are parallel to the top and bottom sides of the outer rectangle.

edge

The

of the

left

edge

of the inner rectangle lies 0.5 inches to the right of the left

outer rectangle. The top edge of the inner rectangle

lies

0.5 inches below

the top edge of the outer rectangle.

The perimeters

j_

of

both rectangles consist of pure black lines that are 36 inch thick.

Other than the rectangles, everything else

in

the figure

is

pure white.

Notice that the preceding description begins by labelling the two parts and sticking to these

same part names throughout the You would probably hate

to read

description.

an entire book written with so

little

imagination or verve;

however, in some situations, a completely objective and robotlike description

what

is

exactly

scientific readers need.

m Professional Secrets > Precision Descriptions

127

The Hardest Part For

many

of Writing

people, the toughest part of any writing project

is

the beginning. This

natural. At the beginning of a writing project, a desolate white screen

is

only

is

staring back at

you. You have not yet established a track record with this document. Doubt gobbles at your soul.

"Hmm, maybe

on Channel

Many

I'll

take a break

and

get a snack now.

people make the mistake of trying to write books

Don't do

this.

Professional writers almost never

page to write. In pressure

on

chapter will

Oh

look

—

celebrity

bowling

fact,

sentence

yourself? Write the fly

1

of page

first

this.

linearly,

Page

1

is

from page

last.

1

to page n.

almost always the hardest

the hardest line to write.

is

1

chapter

do

By the end of the

Why put

project, the

so

much

opening

off your fingertips.

What should you some confidence

write

first?

I

recommend

writing the easiest chapter or section

first.

Build

in yourself before tackling the hardest parts.

Writer's Block has. Even Stephen

Have you ever had writer's block? Of course you have. Everyone King has days where he can only write a single novel. Try the following tactics to •

overcome occasional bouts

of writer's block:

Try writing passages without self-editing. In other words, just try blasting out a

bunch

of

sentences and force yourself not to erase or rewrite anything during

this blast. •

more than

away from room for half an hour. Take a shower, take a walk, talk to a friend... anything! Just make sure to engage your brain with something other than writing for 30 minutes. Then come back and try again. If

you've gone

15 minutes without writing anything, step

the computer and leave the typing

•

Reread something you wrote that you are proud

succeeded before as a writer and that you Writer's block

smacks

will,

of.

Remind

therefore,

yourself that you've

succeed again.

By removing the self-doubt, you can often

of self-doubt.

accomplish great things. •

Figure out what times of day you are

most productive as a

writer

and

restrict

your writing to those times.

The most general advice when faced with process and get out of the rut you're

writer's block

in.

E 128

is

4!"

Professional Secrets > The Hardest Part of Writing

is

simply to change your

Summary When

of Professional Secrets

reviewing your professional documentation, ask yourself the following questions:

•

Have you used enough examples?

•

Have you used appropriate examples

would be hard

(It

for

to have too

many

examples.)

your audience? Will your audience struggle

trying to understand your point? Conversely, are your examples too trivial

and obvi-

ous for the target audience? •

Have you presented examples example require information

in the right

sequence? For instance, does the

that can only be learned

first

by reading the second

example?

you have used Q-and-A format, do your questions cover the topic

•

If

•

Have you only described important concepts

in a single

sufficiently?

way? Hopefully, you have

described key concepts in terminology in multiple ways so that readers

understand the •

first

Have you picked an appropriate tone your readers want something audience

•

is

in

who

don't

explanation might understand the second explanation.

no mood

light?

for

your documentation? Are you serious when

Do you

put out whoopie cushions

when your

for levity?

Have you picked an appropriate pace?

Do you

write too quickly or too slowly?

Do

you slow the pace to handle tricky concepts? •

Assuming

that the pace

and tone permit, have you provided

sidebars, footnotes, or

other digressions to wake your readers up? Will your digressions interest your audi-

ence or are they just eating up paper? •

Have you written obvious information

that

your target audience already understands

or do you take a step beyond what they already

know?

Is

your documentation worth

their time? •

Have you accurately described

that

which requires objective description?

Professional Secrets >

Summary

of Professional Secrets

129

SECTION 3

Writing: Specific

Kinds of Documents

his section explains \

scientist or

how

to

produce

specific kinds

of documents that the average

engineer would have to write, including the following:

•

manuals

•

Web

•

proposals

•

specs

•

lab reports

sites

•

PowerPoint presentations

•

e-mail messages

131

CHAPTER

11

Manuals

manual ter a

is

a

document

technology.

that explains

A document

manual, but a document describing

Good manuals

are priceless;

how

to

perform

how

bad manuals are

to drive that car or

torture.

have valuable experience with both kinds of manuals.

what you

like,

The following

No

and avoid what you is

a

list

cookbooks

•

tutorials

•

guides

•

references

•

nonverbal manuals

is

A

thorough documentation

tion, this chapter

ments

a technical person,

When

is

a

not a

manual.

you already

writing a manual, emulate

inherently better than another, although certain styles are better in certain

manual can sometimes include

single

its oil is

or mas-

detest.

uations. Experienced writers master several styles situation.

As

change

model

of the most popular styles of manuals:

•

style

a task, use a product,

detailing the history of a certain car

set

and choose the appropriate one

sit-

for each

includes several of these styles. Alternatively, a

several styles. This chapter explains

examines online help and

release notes,

them

all.

In addi-

which are two types of docu-

related to manuals.

This chapter concludes by describing the following •

prefaces

•

glossaries

•

tables of contents

•

indexes

common components

of manuals:

Manuals

133

Manual A

culinary

two

Cookbooks

Style:

cookbook

where each recipe contains the following

consists of a set of recipes,

sections:

•

a bulleted list

•

a

numbered

of ingredients

list

of steps

Cookbook-style manuals also provide steps.

a

Cookbook-style manuals are ideal

in a highly specific way.

compound from two manual would

bulleted

list

of ingredients and a numbered

for describing tasks that the reader

For example, a manual explaining

other

specify the

compounds

list

lends

how to

itself perfectly to

list

of

must perform

create a certain chemical

the

cookbook

style.

The

of ingredients (source compounds, goggles, Bunsen burners,

thermometers, and so on) and the steps to synthesize the new compound.

Avoid cookbook

style

when

the technology cannot be described as a series of discrete steps.

For example, cookbook style

is

not appropriate for teaching someone

how

to

code in

a

computer language.

The keys •

to writing

good cookbook-style manuals

Think through the

list

of ingredients

carefully. Writers are usually pretty

remembering materials but not so good are also •

7 for •

If

some of the

Keep each step

are as follows:

at

remembering

that

good

ingredients.

discrete.

Do

not cram multiple tasks into a single step. See Chapter

more suggestions about

creating

good

lists.

Define success, as in the following example:

the cells are glowing with a distinctly greenish

tint,

then you have performed steps

1-24 correctly and can proceed to the next section.

•

If

Define failure and explain what to do about

it,

as in the following example:

the cells are not glowing green, then you must perform steps 19-24 again, paying

particular attention to the temperature of the

The following

is

a

enzyme

in

step

19.

cookbook-style software manual for experienced users. Notice the

descriptions of failures (in steps 4 and 7) and the description of success (in step 7).

1 134

at

equipment and energy

Manuals > Manual

Style:

Cookbooks

Cookbook Example:

Carambola

Installing the

Server

Requirements To perform the

installation,

•

CPU—

•

RAM— 512MB

Pentium

you need

at 1.5

•

Network— 10 MB/s

•

Operating system

•

Browser

a

PC

with the following

minimum

requirements:

GHz

— Red Hat AS3 or — Mozilla or 1.7

later

later

Installation

To

install the

Carambola

1.

Start Mozilla.

2.

Browse

Server,

to the following

perform the following

steps:

URL:

http://www.carambolapublishing.org/ws/download

The Download menu appears. 3.

In the

Download menu, click the Download and Save

The

server

then

a

at step

downloads the software.

network

failure has

If

the

download

option.

takes longer than 20 seconds,

the download. Wait a few minutes, then start over

1.

4.

Start a bash shell.

5.

Invoke the following $

doomed

menu

command from

the bash shell:

/tmp/inst_carambola

The inst_carambola

script will install

and

start the

Carambola

Server, overwriting

any previously existing installation of the Carambola Server. 6.

In Mozilla,

browse

to the following

URL:

http://127. 0.0. 1:1984 If

Mozilla displays an orange

bola Server.

If

fruit,

then you have successfully installed the Caram-

Mozilla does not display an orange

fruit,

terminate the bash shell and

redo steps 5-7.

Manuals > Cookbook Example:

Installing the

Carambola Server

135

Manual A

tutorial

Style: Tutorials

a

is

document

•

by the hand and leads them gently through

that takes readers

the initial use of a product or technology.

The keys

good

to writing

tutorials are as follows:

Give readers a taste of success as soon as possible, preferably on the

first

page.

Reassure readers that they can learn this technology. •

Take very

would •

how

to learn

Move lost

not leave out information that

seems obvious

it

1

not

will

make

•

Call out everything that

•

Test

•

Introduce topics one

your

a

beginning reader

to you.

don't need to understand geol-

to dig a hole.

fairly slowly, particularly in the

on page

same If

Do

Omit extraneous background information. Readers ogy

•

for granted.

little

find valuable just because

is

it

beginning of the document. Readers

page

to

get

confusing or potentially dangerous.

on beginners; feedback from experts

tutorials

who

2.

at a time, if possible.

Do

is

worthless.

not introduce multiple topics in the

lesson.

you are an expert who

must regain your

initial

is

You

writing a tutorial, you must regain the beginner's mind.

sense of confusion and imbalance with this technology.

It is

some-

times easier for a beginner to write a tutorial than for an expert.

Although

tutorials are

aimed

at

readers

who

are

new

to a technology,

already be expert in an allied technology. For example, surgical device, the surgeons in

devices. Therefore, in

youf

when

your audience might

writing a tutorial for a

new

your audience are already highly experienced with related

tutorials, take

advantage of existing experience by drawing com-

parisons to familiar technologies. Doing so will build a sense of comfort with the

new

tech-

nology.

Remember

that tutorials are often the

readers will have with a technology. petence. However, rial, I'll feel really

The following ple,

some

impression (that tutorial

Web

critical first

impression) that

can imbue readers with a sense of com-

readers find tutorials intimidating. (7/7 don't understand the tuto-

stupid.)

tutorial

is

aimed

at readers

who

are fairly comfortable using

they already understand the concept of pathnames), but

ating

pages with

HTML.

18" 136

first

A good

Manuals > Manual

Style: Tutorials

who

PCs

(for

exam-

have no experience cre-

Most people full-

create

Web

pages

In fact, creating

Web

In this first lesson,

HTML

pages with

you

will create a

can be

— HTML

HTML.

language called

in a

Hedged computer language; you do not need

a

degree

Don't worry in

computer science

PC

is

A browser named

newer than 1995 or

Web page. To perform

a

is

program

Internet Explorer,

might also have browser

is

so,

you are

that allows

and

a different

it is

you

all set.

to access

installed

not a it.

this lesson, you'll

PC must

Your

Web

sites.

have

isn't

need

a personal

important.

browser

a

If

installed.

The most popular browser

is

on almost every modern PC. However, your PC

browser (such as Netscape or Firefox). For

this lesson,

any

fine.

To begin the

lesson,

you must invoke the

named Notepad by

text editor

>Program->Accessories->Notepad. The Notepad program will spring to

lowing

is

to use

of fun.

a lot

computer (PC) running Windows. The version of Windows you use your

HTML

Example: Getting Started with

Tutorial

text into

selecting Start-

Enter the

life.

fol-

Notepad:

HTML is better than ice cream.

Enter that text exactly as

it

appears. Notice that the closing

contains a slash, but the

opening

does not. Congratulations Fi

1

e->Save.

Save the

— you

just created the

A menu appears,

file at

HTML

for a

Web

asking you to select the

file

page. To save this in

which

HTML,

select

to save this masterpiece.

the following pathname:

C:\Temp\IceCream.htm

Note

that the filename

omit

a suffix), then this lesson will not work.

You

suffix .htm. If

are finished with Notepad, so feel free to close

To end

One

must have the

this lesson,

fairly

C:\Temp

open your

simple way

is

to

Web

page

file

on

some other

suffix (or

it.

in a browser.

folder. After arriving, double-click

is

give the

There are several ways to do

do double-click My Computer, and then the IceCream.htm

everything properly, your browser should display a HTML

you

Web page

this.

to navigate to the

document.

If

you did

containing the following

text:

better than ice cream.

Notice that your browser does not display the

or the

.

Manuals >

Tutorial

Example: Getting Started with

HTML

137

Manual A

guide

is

a

Guides

Style:

manual

that readers turn to after reading a tutorial in order to master inter-

mediate or advanced topics. Sometimes the

same manual.

contains

all

a tutorial

In such cases, the tutorial

and guide

are

bundled together within

generally the opening chapter and the guide

is

subsequent chapters.

Guides and tutorials are useful for products where the steps

The keys

reader could use the technology in a different way.

aren't

obvious or where each

good guides

to writing

are as

follows:

•

Empathize with readers. Determine what

skills

your audience wants to learn and

provide them. •

Provide plenty of relevant examples. Provide a large collection of short, simple examples rather than a small collection of lengthy, in

an occasional lengthy real-world example

make •

a

good

examples that

idea. Pick

Include plenty of figures, tables, and photographs to break up the

Provide background information

Structured documentation

ular topic.

When

is is

a

a

popular

when

it

of guides. The central organizing unit in

style

chunk, which

helps explain a topic.

is

a short, discrete unit or lesson

Then

Each chunk builds on the previous chunk.

•

Each chapter consists of a

•

Chunks

series

all

which each chunk

It is

aimed

chunks preceding

this

Manuals > Manual

new

other guides in the Spring is

either

The following example demonstrates on HTML.

a partic-

at a

page.

Into... Series) are

a single

chunk of a structured documentation guide

moderately experienced

Guides

written as structured doc-

one or two pages long.

chunk have explained

Style:

all

of related chunks.

usually begin at the top of a

This guide (and

on

the writer follows these rules:

•

in

monotony of large

creating structured documentation, the writer begins by organizing

material into chunks.

umentation

will

text.

structured documentation

138

is

sense to your target audience.

blocks of •

complex examples. However, sprinkling

HTML

the

developer.

and

tags.

Assume

that the

HTML

Guide Example: Creating

Each

cell in

the top

row of a

of every row should also be

a

table

should be

To

header.

a header. In

Headers

some

create a header in an

tables, the leftmost

column

HTML table, specify the

(short for table header) tag.

You can place

a tag

anywhere you would put

a tag, except the resulting text

tags

row of a

in the first

is

table.

a



usually centered

You might

tag.

and

The

tag behaves just like

in boldface. Typically,

also put tags in the first

you place

column of

each row.

For example, Example 11-1 uses the tag to create headers for both columns of a two-

column

table.

EXAMPLE

11-1

The tags specify Movie and Description as headers

Movie	Description
Casablanca	Bogie must choose between Bergman and the right thing to do.
wizard of Oz	A depression-era Kansas teenager chooses between ultimate power and the right thing to do.

The

resulting

HTML

table looks as follows:

Movie

Description

Casablanca

Bo 9 ie must c h° ose between Bergman and

the right thing to

"do

Wizard

Oz FIGURE

of

A depression-era Kansas teenager chooses between ultimate

11-1

An HTML

power and

the right thing to

do

table containing proper headers.

Manuals > Guide Example: Creating

HTML

Headers

139

Manual

Reference Manuals

Style:

Like structured documentation, reference topics. like a

The

topics in a reference

Each topic

hierarchically.

By

the engine as a

The keys

some

much

reference manuals arrange reference pages

manual describes

or

a discrete part

component of

would contain 100 reference pages, where each reference page contrast, the guide for this engine

whole or how

to writing

would

likely focus

on how

detailed a

to

maintain

to maintain different engine subsystems.

good reference manuals

are as follows:

Use the same format for every reference page. In other words, each reference page should contain the same

•

into a set of focused

example, consider an engine that contains 100 parts. The reference manual

for this engine

single part.

in a reference

manuals organize material

are typically organized in alphabetical order,

dictionary or encyclopedia, although

a system. For

•

manual

set

of headers.

Provide examples on each reference page,

if

possible.

Many

writers shy

away from

examples on reference pages; however, most readers love examples. •

Provide abundant hyperlinks or cross-references pointing to related topics.

•

Provide diagnostic information.

•

Think of reference pages

What

error codes are emitted

when

this part fails?

as reminders, not tutorials.

Reference manuals are quite popular for describing software such as Application Program-

ming

Interfaces (APIs)

and

shell-level

commands.

Typically, software reference

manuals

are distributed online only.

Programs now generate many reference pages automatically. For example,

a

program

called

javadoc automatically generates reference manuals for Java APIs by examining Java source

program

code and programmers' comments. Using

a

amount of time and synchronizes changes

to software with

addition, these programs

do

a better

like

javadoc saves

a

tremendous

changes to documentation. In

job of capturing certain kinds of details, such as the

signatures associated with APIs. However, the resulting reference manuals are only as as the

ple

comments

that

code seldom make

software engineers

programmers have provided. it

fortable with the

140

UNIX

Manuals > Manual

into

illustrates a reference

page aimed

operating system.

Style:

making

Reference Manuals

the

at

comments

good

and exam-

into automatically generated reference manuals. In addition,

do not put enough time

The following example

Niceties such as diagnostics

many

clear.

mathematicians

who

are

com-

Reference Example: The prime

Utility

Name prime

— determines whether

Synopsis prime [-v]

ill

a given

number or range of numbers

is

prime.

[«2]

Options Verbose mode. Displays output as

a full

word

(for

example, "PRIME").

Description

Use prime to

test

number.

just that

one or two integers If

you specify two

default, prime returns P

if

for primality. If

you specify one

integers, prime tests

the specified

number

is

all

the

prime and

integer, prime tests

numbers

in that range.

C if the specified

By

number

is

composite.

Troubleshooting Values of nl and n2 must be integers between 2 and (2

number

outside this range or

if

you specify

6

-

1),

inclusive. If

a noninteger, prime returns

X

you specify

a

(or "OUTSIDE

RANGE" in verbose mode).

Examples The following example uses prime $

prime

prime

number

11

is

prime:

11

The following example $

to indicate that the

11

tests the integers

between

11

and

13, inclusive:

13

P

c p

The following example generates verbose output: $

prime -v

11

PRIME

See Also led, gef

Manuals > Reference Example: The prime

Utility

141

Manual As

name

its

Nonverbal Manuals

Style:

manual contains no words;

implies, a nonverbal

and photographs. Creating artistic skill. Nevertheless,

a professional

it

contains only illustrations

nonverbal manual generally requires great

any of the following situations lend themselves to nonverbal

manuals: •

A

•

The

cost of translating text

•

The

skill

large percentage of the target audience

to be mastered

words would

is

is

is illiterate.

prohibitive.

best described through figures or photographs. (Frankly,

just get in the way.)

At the risk of stating the obvious,

I

should say that nonverbal manuals are only appropriate

for products or technologies that can be described pictorially. For example, a

language manual activities

is

computer

hardly a good candidate for a nonverbal treatment. However, physical

such as the following would be good candidates:

•

simple medical procedures, such as certain kinds of

•

assembly manuals, such as

•

various physical activities, such as

a

manual showing how

how

first

to

to use exercise

aid

assemble

a bicycle

equipment

Generally speaking, nonverbal manuals should be quite short, as in Figure 11-2 that shows

how

to put

on

a piece of safety

equipment.

i:

:

IS

FIGURE

11-2

A nonverbal manual showing how

to put

1142

Manuals > Manual

Style:

Nonverbal Manuals

on a face mask.

Online Help: Overview

Many

readers prefer online help to traditional manuals, primarily because

help brings practical answers quicker than traditional manuals.

going to an information booth and getting an instant,

knows

it all

manuals

but doesn't

feel

obligated to

tell

are like going to your Uncle Charley

when

of suspenders

you want

all

to

know

is

The Differences between Online Help and It

you

used

to

if terse,

Good

is

answer from someone

To many modern

all.

good online

online help

like

who

readers, traditional

who forces you to listen to the entire history how to make another notch in your belt.

Traditional

Manuals

be easy to distinguish online help from traditional manuals because

manuals were distributed

traditional

manuals

online help and traditional copy, often

in

an

HTML

hard copy. Now, however, the

in is

blurry.

line

between

Most product manuals now ship

in soft

format that looks rather similar to online help. The few

remaining distinctions between online help and traditional manuals are as follows: •

Online help pops up typically

do

when

a user selects a

Help menu; traditional manuals

not.

•

Online help does not contain page numbers; traditional manuals do.

•

Online help

is

authored with special tools

manuals are usually

written with

(for

example, RoboHelp); traditional

word processors such as Microsoft Word.

Categories

Online help •

falls

Context

into

two broad categories: These automatically display

sensitive.

a help screen relevant to the reader's

current situation. For example, suppose you are looking at a properties. If

you request

menu

to set screen

help, a context-sensitive help system displays a help

file

about setting screen properties. •

General. These provide multiple help one.

If

you are looking

eral help

system offers you a

Context-sensitive help

is

menu

at the

list

of

files

and require the reader

to set screen properties all

help

files

to pick the right

and request

obviously more valuable to readers than general online help. As

you might expect though,

it is

much

harder to produce context-sensitive help than general

help. Creating context-sensitive help requires careful coordination of writing

engineering.

Of course,

help, a gen-

and you choose between them.

if

the software developer

is

and software

also the writer...

Manuals > Online Help: Overview

143

Online Help: Best Practices

I

recommend

the following approach for creating context-sensitive or general online help:

of

the tasks that readers might need to perform.

1.

Create a

2.

Write a separate help

list

all

file

for each task. For example, if your

then create 100 separate help 3.

Add

4.

Beta-test

We now

hyperlinks to lead readers to related help

dive a

and

list

consists of 100 tasks,

files.

files.

refine as necessary.

deeper into the preceding

little

list.

Create a List of Tasks

The engineering team should product. single

When

creating the

sit

list

down

together and figure out what users will do with the

of tasks, keep each task highly discrete. Don't assume that a

—

menu entry in a graphical user interface corresponds to a single task

to multiple tasks (or to

of concepts.

If your list

none

at all). In addition to tasks,

of concepts

is

you might

also

it

may correspond

want

long, put the concepts into a traditional

to create a

manual

list

instead.

Write Help Files

The keys •

to writing

good help

Keep each help

file

files

are as follows:

as brief as possible. Ideally, each help

file

should

fit

inside a single

screen so that readers don't have to scroll.

numbered

•

Prefer

•

Don't digress, don't footnote, and don't wander. Keep each help

lists

to bulleted

lists.

file

focused on a sin-

gle, discrete task.

"^QUANTUM LEAP Sometimes you must if

many

help

files

divide a lengthy help

file

are too lengthy, online help

information. Consider writing a traditional

into

may

manual

two separate help

files.

However,

medium

not be the proper

for this

instead.

Beta-Test and Refine

Have

real users test

help

files.

system provide those topics? index?

Good

Determine what topics they are searching If so,

do these topics appear

for.

Does your help

of contents and the

online help systems are dynamic, adding, changing, or removing screens to

meet customer needs.

144

in the table

Manuals > Online Help: Best Practices

Online Help Examples

Suppose

wants to change the font of her favorite program. She

a user

which causes the program's online help system tab

on the online help system and searches

to spring to

11-2

clicks the Hel p button,

She then

for the phrase change font.

the online help system displays the less-than-perfect help

EXAMPLE

life.

file

shown

clicks the Index

Almost

in

instantly,

Example

11-2.

Online help (suboptimal)

Display Properties Screen

The Display Properties screen In particular,

you control the display properties

lets

of

your screen.

you can use the Display Properties screen to control the following two

properties: •

the background image displayed on the screen

•

the font

You invoke the Display Properties screen by selecting File->Properties. The Display Properties screen appears, which looks like this:

Display Properties

Background Image

3

O

Font

Pastoral

'£

Agrarian

C

Anal Helvetica

Canyon

Times

Waterfront

Courier

(

Ap p ly

Pr o p e rty C h a rig e s

j

The program uses the background image •

in

the splash screen that appears

•

in

the Build screen displayed

in

two places:

when you

first start

when you request

the program

a build

To change the background image, select from one of the four choices and then click

Apply Property Changes.

The program uses the font settings are sans

serif,

the Times font

is

to display

a serif font,

all its text.

The

and the Courier

Arial

font

is

and Helvetica fonts a fixed-width font.

Select the desired font and then click Apply Property Changes.

Manuals > Online Help Examples

145

The preceding online help

how

to find out

describing

file

change

to

contains multiple problems.

the options available

all

through quite

a bit

files

on

this screen.

Consequently, the reader had to wade

of extraneous information about other parts of the screen before hitting

the part about changing fonts.

help

The poor reader simply wanted

However, the writer seemed to be more concerned with

fonts.

To correct

this

problem, the writer should have created two

—one on changing backgrounds and another on changing

The reader wants information

quickly, but the preceding online help

find the relevant information. For example, the reader needs to

information resides

access. This

Finally, the less in

in the online help

file,

but

it is

makes

file

The online help

file

file.

it

hard to

know which menus

to

diffuse rather than focused.

information on fonts ("Arial and Helvetica are sans-serif fonts")

an online help

EXAMPLE

fonts.

is

fairly

worth-

Readers want quick recommendations.

shown

in

Example

1

1-3 provides

improvements.

Online help (improved)

11-3

Changing Fonts To change fonts, do the following: Select Fi 1 e->Properti es.

1.

The Display Properties screen looks as

follows:

Display Properties

3 Prefaces

149

Preface Example

The Carambola 4000 scanning Carambola

electron microscope

is

Industries. This microscope offers greater

from

the latest mid-level product

power and

a

simpler interface than

previous electron microscopes.

This manual

more,

it

aimed

is

at

readers

who

have

at least a bachelor's

degree

Further-

in biology.

assumes that you are already familiar with basic microscopy techniques and

Our

minology.

research suggests that this

model

is

most appropriate

for scientists

ter-

who

already have at least one year of experience using an electron microscope. After reading this manual, you will

know how

to use, troubleshoot,

and maintain the Car-

ambola 4000.

The manual

consists of four chapters,

•

Chapter

•

Chapter 2

1

which are organized

as follows:

provides a tutorial to get you started with easy tasks. is

a long chapter that explains the

more advanced

features of your

microscope. •

Chapter 3 explains what to do

•

Chapter 4

details routine

if

your Carambola 4000 stops working

perfectly.

maintenance procedures and cleaning techniques.

At Carambola Industries, we think that readers prefer to learn by using the product. Therefore,

that

I

Chapters

1

and 2 show you how

to use the

Carambola 4000

to scan the

sample

want

to

thank Mark for

his

knowledge of

edge of electron microscopy, and

^QUANTUM

cell

structure, Lauren for her

Sal for his extraordinary

mushroom

amazing knowl-

pizza.

LEAP

As mentioned

earlier,

many

readers skip over prefaces. For this reason, Chapter

should also define your audience. For example, you might consider providing a slightly

Chapter

150

slides

accompany the microscope.

modified version of the second paragraph (This manual 1

as well as

in

the preface.

Manuals > Preface Example

is

aimed

at...) in

1

Glossaries

A

glossary

is

a

small dictionary that defines the terms used in a particular document,

or enterprise.

site,

tion

—

When you

particularly those to

are

which

several people contribute

—

I

highly

the project by creating a glossary. Getting contributors to agree will save all sorts

The keys

of time and aggravation

recommend

later on.

to writing a professional glossary are as follows:

Keep definitions short.

•

Provide relevant example usages in your definitions, where appropriate. Limit the terms in the glossary to primary concepts. Don't get bogged

too •

starting

on terminology upfront

•

•

Web

producing any form of lengthy technical communica-

many secondary

Keep the form of each term grammatically or that

more

all

down

defining

terms.

terms are plural. However,

natural in their plural form;

if

parallel.

you pick

do not

Ensure that

all

terms are singular

singular, note that

some terms

are

force a natural plural into the singular just

for the sake of consistency. •

Keep the form of each

some terms with •

full

Write unambiguous definitions. to multiple terms.

•

definition grammatically parallel. For example,

do not define

sentences and others with partial sentences.

Compare and

Make

sure that the

same definition could not apply

contrast terms.

Target your audience appropriately. Define

all

the terms in the

document

might

that

be new or unfamiliar to your target audience. Don't define words that the entire audience already knows. •

Present terms in alphabetical order. Resist the temptation to organize terms by

some

other categorizing scheme. •

Provide hyperlinks to other terms within the glossary In

some

cases,

you may also provide hyperlinks

to

if this is

an online document.

terms defined

in

other glossaries;

however, make sure that the hyperlink opens the external glossary in a separate win-

When

dow. to,

•

referring to other glossary terms, use phrases such as See also,

and Contrast

Aim

to create a "closed-circuit" glossary in

in definitions are,

The sample

glossary

Compare

with.

which any unfamiliar terms mentioned

themselves, defined in the glossary.

on the next page

is

aimed

at a

well-educated lay audience. See also

the glossary of technical writing terms that appears at the

end of

this

book.

Manuals > Glossaries

151

Glossary Example: Tropical Weather Terms

extratropical cyclone

An

organized low-pressure area formerly a tropical cyclone whose energy source ,

,

sharp temperature difference between tropical cyclone

warm

and cold

tropical air

arctic air.

is

the

Contrast with

.

eye

The

center of a hurricane which

marked by clear

usually

is

,

skies,

low winds, and the lowest

central pressure.

The

strongest transient

sustained winds

wind speed. Gusts

in a

hurricane are typically

15%

higher than the

.

hurricane

A

tropical cyclone with sustained

winds of

at least

65 knots and an eye

.

knot

A

unit to measure sustained

winds or gusts

.

A

knot

is

equivalent to 1.15 miles per hour.

low-pressure area

A

region marked by counterclockwise

wind

circulation (in the Northern Hemisphere),

lower than average barometric pressure, and generally stormy weather.

sustained winds

The average wind speed utes).

measured over

as

Contrast with gusts

a certain period (usually

one minute or

five

min-

.

tropical cyclone

A

low-pressure area whose energy source

winds

tropical

A

is

warm

ocean water and whose sustained

are greater than 25 knots Contrast with extratropical .

.

storm

tropical cyclone having sustained

winds between 35 and 64 knots.

1. Most terms are in singular form; however, gusts and sustained winds more natural and more frequently used for these terms.

Ill' 152

cyclone

Manuals > Glossary Example: Tropical Weather Terms

are in plural

form because plural

i

Tables of Contents

Technologists are busy people

who

rarely have time to read

the table of contents

is

very important.

You might be thinking,

matically generates the table of contents.

How can

of contents by picking chapter and header

The following •

are

some

Think of all the

lists

names

I

change

it?

from cover

My word

to

this reason,

processor auto-

Well, you enhance the table

good

table of contents:

headers within each chapter as forming a

first-level

consistent header •

linearly

titles wisely.

guidelines for creating a

the rules for creating

manuals

by searching the table of contents. For

cover. Therefore, they often seek topics

described in Chapter

to ensure parallel

7.

list.

Then, follow

In particular, use grammatically

lists.

Ensure that your header names contain key terms to attract the eyes of a browsing reader. For example, if

then

make

you

feel that

readers are interested in mitochondrial

DNA,

sure that at least one of your chapters or headers contains this term.

•

Keep chapter and header names

•

In a lengthy

relatively concise.

manual, organize related groups of chapters into sections.

For instance, Example 11-4 contains a flawed table of contents that does not follow some of the preceding

EXAMPLE

5

11-4

A

rules.

Partial Table of

Contents (with flaws)

Introduction to Tables

7

Creating Tables 7

Rows 8 Cells

9

Creating Headers () 10

Rules (Lines) and Shading (the gray patches

6

in

some

cells)

11

Tricks with Tables 13 Placing a Table within a Larger Table 13

Images Inside Cells 15 Spanning Rows (rowspan Attribute) 16

Manuals > Tables

of

Contents

153

—

The

table of contents

•

shown

in

Example

The headers within Chapter

5

begins with a verb, while Cells

•

1

form is

1-4 contains the following problems:

a nonparallel

just a

begin with a verb or

list.

begin with a noun.

so that they

all

The headers

are missing several keywords that readers

ple,

many

For example, Creating Tables

noun. The writer must rename the headers

all

would

likely seek.

For exam-

people reading this book would seek tag names in the table of contents.

One of the

headers

Creating Headers ()

—does contain

a tag

name; most of the

other headers require them. •

The

last

belongs

header in Chapter 5

is

too long. This header contains information that

paragraph, not in the header

in a

itself.

In fact, the complexity of the header

strongly suggests that this section be divided into two sections. •

The two chapters could be grouped

Example 11-5 shows

EXAMPLE

11-5

A

a

into a section

named

somewhat improved version of the

Partial Table of

table of contents.

Contents (with improvements)

Section

2:

Introduction to Tables

Tables 7

Creating Tables with Tag 7 Inserting

Rows

with Tag 8

Inserting Cells with Tag 9

Creating Headers with Tag 10 Placing Rules with border Attribute

11

Placing Shading with bgcolor Attribute 12

Tricks with Tables 13 Placing Tables within a Larger Table 13 Inserting

Images inside Cells 15

Spanning Cells across Rows 16

154

Manuals > Tables

of

Contents

Tables.

Indexes

Creating a good index

supreme patience and readers. After

find the

is

boring and time-consuming. Creating

a great

index requires

diligence. Despite the pain, the results are extremely valuable to

the majority of technical readers go straight to the index. If they can't

all,

magic word or phrase

in the index, then that topic

is

lost to

them, even

well

if it is

covered in the manual.

Many

people mistakenly believe that indexing involves highlighting selected words, kind

of like students do with a yellow marker. In

Even many professional writers

reality,

good indexing

they don't have the requisite

feel

is

far

skill

more

sophisticated.

or patience and turn

over the task to trained professional indexers.

The Golden Rule

When

of Indexing

creating an index, pretend you are a reader, and ask yourself the following

question:

What would All

I

look up

in

the index?

other indexing rules are subservient to this golden rule of indexing.

The following

guidelines help you

implement the golden

rule of indexing:

•

Create precise index entries; avoid vague entries.

•

Avoid misleading entries that could send readers off on

•

Permute index entries so that

•

Provide index entries for related concepts, not just the

•

Use grammatically consistent forms for

•

Don't forget to index the information appearing

How Long Should an

a

wild goose chase.

a single entry phrased as x,y

all

is

literal

also listed

under

y,x.

words on the page.

entries. in

graphics and tables.

Index Be?

all, a single page can sometimes be adequately indexed with only two or three index entries, while a single juicy paragraph might require a dozen entries. As a broad estimate, I'd say that good It

is

hard to pinpoint the correct length for an index. After

indexes generally

consume

5%

to

7%

of the length of the

body

of the book.

Manuals > Indexes

155

Indexes: Providing Concise Entries

To explore indexing, consider the following passage from

a vegetable gardening

manual:

Adjusting Acidity

Most vegetable plants prefer a

pH between 6.0 and 6.8. A more acidic soil. The king happiest with a pH around 4.5.

slightly acidic soil with a

few vegetable plants, such as the tomato, prefer a the blueberry bush, which

of

the acid lovers

In

most eastern parts

way

is

pH

to raise the

United States,

of soil is to

United States,

of the

of the

soil

is

slightly

tends to be too acidic. The easiest

spread crushed limestone. Over

too alkaline. Spreading sulfur

soil is

is

many western

parts

an inexpensive way

to

lower the pH.

Some

of the obvious index entries in the preceding passage are as follows:

acidity alkalinity

blueberries

eastern United States

soil

limestone

PH sulfur

tomatoes vegetables

western United States

The preceding

more

entries are okay, but they are a

more

useful because they are

acidity of

garden

alkalinity of

soil

pH

eastern United States limestone, to adjust of

garden

sulfur, to

little

specific:

soil

garden

blueberries, proper

pH

soil

of soil

soil,

adjusting

pH

pH

soil

adjust

pH

tomatoes, proper pH of vegetables, proper

pH

western United States

soil

of soil soil,

adjusting

pH

1

156

Manuals > Indexes: Providing Concise Entries

too general. The following entries are

Terms

Indexes: Permuting

The wise indexer permutes

the

words

in

some multiword index

entries,

making each

appropriate permutation a separate index entry. For example, consider the following entry:

acidity of

garden

soil

The preceding entry should garden soil,

soil,

acidity of

acidity of

You could

also

permute the following entry:

eastern United States

soil,

adjusting

pH

such as the following:

to entries

pH, eastern United States soil,

lead to the following additional index entries:

soil

eastern United States

United States, eastern

soil

Providing Second-Level Entries

Permuting entries invariably creates the need for second-level index keeping both of the following terms

It

soil,

acidity of

garden

soil,

adjusting

in

looks

more

at

the first-level

is

entries.

For example,

not optimal:

eastern United States

professional to keep soil as a first-level entry and to create second-level entries

as follows:

soil

acidity of in

eastern United States

Manuals > Indexes: Permuting Terms

157

Indexes: Providing Entries for Concepts

The golden

rule of indexing yields the following less-than-obvious entries

from the

gar-

dening passage:

sweetening souring

Neither of these terms appears in the

many

Looking is

know them.

gardeners at a

higher conceptual

this section all

you have

about? In

to think

text, yet

(Acidic soil

level,

many

is

they are worthwhile index entries because

too sour

and

requires "sweetening.")

sometimes you have

cases, the

answer

is

to

found

sit

back and ask yourself, what

in the header. In other cases,

beyond the obvious. For example, the following

entries

would

also be

worthwhile:

crops, improving through

modifying,

pH balancing

pH

performance

of garden, effect of

pH pH balancing

yield of garden, improving through

Parallelism in Index Entries

Indexes are a form of

list.

Therefore, you

Most index entries are either nouns

must apply the laws of parallelism to them. The following simple rules

or verb phrases.

should keep your index entries parallel: •

Place nouns

•

Place verbs

in

their plural form. Thus, specify potatoes rather than potato.

in their

participle form. Thus, specify creating rather than create or

creates.

158

Manuals > Indexes: Providing Entries

for

Concepts

Summary

Manuals

of

Before writing a manual, you should develop a complete doc spec and, possibly, a docu-

mentation project plan. Refer to Chapter 18 for

details

on planning, reviewing, and editing

manuals.

While writing

a

manual,

refer to Section

•

Does your preface (or Chapter should be reading

•

Do

1, if

you don't have

manual and what

all

aspects of your

man-

a preface) explicitly identify

the reader will get out of listings for

who

it?

every keyword or concept

might seek?

Does the opening section of each chapter introduce the chapter's closing section of each chapter

•

of this book to optimize

your table of contents and index contain

that a reader •

this

1

following questions:

ual. In addition, ask yourself the

Does your manual contain

summarize the

a nice

mixture of

topic?

Does the

chapter's topic?

text, tables,

and graphics, or does one

of those weigh too heavily? Generally speaking, manuals should contain a nice bal-

ance of words and pictures, although certain topics necessitate an unbalanced presentation.

and

a

A manual

won't contain a •

•

lot

scientists

of graphics.

terms and definitions grammatically consistent? Could the same

more than one term?

Do

the chapters follow naturally from each other, or

more

do you need

to reorganize

them

logical order?

Are any chapters too long? Divide lengthy chapters into two or three chapters. By the

some

writers feel that

all

chapters should be about the same length, but I've

never heard a compelling argument as to

Do

why

that

would

benefit the reader.

certain chapters only have significance for a tiny percentage of the target audi-

ence?

If so,

they should

While writing online

become appendices.

help, ask yourself the following questions:

•

Does your online help cover

•

Is

each online help section

Can

all

(or nearly

fairly discrete,

ferent online help sections to •

text,

In a glossary, are all

way,

•

much

and engineers about technical writing probably

definition apply to

into a •

of schematic diagrams probably won't contain too

manual on teaching

all)

of the topics that readers seek?

or will readers be forced to read

many

dif-

answer their question?

readers easily find the topics they seek?

Manuals > Summary

of

Manuals

159

CHAPTER

:

12

:

Web

The

Sites

Internet

is

big. Really big.

The

or other immeasurably.

yada. In the time

it

Important, too. Search engines have helped something Internet has caused a fundamental change in yada,

took you to read

this

paragraph, 24

new Web

were blah,

sites

blah, blah...

Having

satisfied the legal

now move on

requirements for

to the subject of this chapter,

information over the Web. This Rather, this

is

a

is

all

technical books published since 1994,

which

is

how to

chapter about designing and implementing

vey technical or scientific information. Nevertheless, a will

Is

come

in

HTML, JavaScript, Web sites that

not a chapter about

handy

as

you read

little

links,

which make

Furthermore, the

it

or servlets.

con-

effectively

familiarity with basic

HTML

this chapter.

Web different from creating content in Web and paper are different media. After all,

creating content for the

ual? Well, clearly the

can

I

present technical and scientific

a traditional paper

the

Web

man-

provides hyper-

easy for users to bounce around like dust specks in Brownian motion.

Web offers multimedia, so Web sites can explain concepts through speech

or music or animation. In

some

sites.

ways, paper documentation has recently begun to act

For example, consider this very book you are

chunked

to read this

something out of

it.

book

(from page

1

Web pages.

straight as

how

the

like

Web

book

is

Further note that

through to page n) to get

you would when browsing

a

site.

Television

and the Internet have made us

reason to editorialize against

Web

linearly

You can bounce around randomly

more and more

reading. Note

into bite-sized morsels, roughly the length of proper

you don't have

Web

now

it,

a society

and the wise

of information nibblers. There

Web developer doesn't

try to fight

it.

is

no

The wise

developer simply embraces the notion that readers have Attention Deficit Hyperac-

tivity Disorder.

mi Web

Sites

161

Plan Your

A good

Web

Site

plan improves your chances of

Web

success. This

chunk provides some planning

suggestions.

Define the Site's Purpose

Your plan should begin by identifying the purpose of the

Web

the following

site, as in

statement:

Web

Site

This

Web

Purpose recent scientific research on citrus trees and

site will distribute

professional citrus farmers

fruit to

Florida.

in

Define Your Audience

As with any form of communication, begin by defining your audience. definition topics explored in Chapter 2 are also applicable to

ommend

that

similar to the

you begin planning your

Web site

one shown

Supplement

in Table 2-1.

Web

following additional topics for

by

filling

Web

All of the audience

sites.

Therefore,

I

rec-

out an audience definition chart

that table

by supplying answers

to the

sites:

How will users find your Web site? Typically, visitors will find your Web site through

•

a search

engine and from hyperlinks in

Web

find your

engine

sites will visitors hit after visiting

site as

Web

site. If

you expect

visitors to

one piece

Understand what piece your

a search

site?

will direct visitors to other

View your Web

a related

through a search engine, what keywords should trigger

on your Web

hit

What Web

•

site

Web in

Web

sites,

Web

your

site?

Perhaps your

Web

site

or perhaps a search engine will direct them.

your target audience's information jigsaw puzzle.

site will

provide and what pieces other

Web

sites will

provide.

Create a List of Pages

Your plan should contain first

a

If

create a

list

Web

first

site will

The home

a

list

of

and then

contain

Sites

> Plan Your Web

at

what information should be

pages, consider organizing

Site

Web

in

each of them.

pages hierarchi-

the top of the hierarchy. Just below the

you expect users

If Web

figure out

is

Web site. Many designers Web pages. Other designers create

pages constituting your

many Web

page, of course,

are the key secondary pages that

162

Web

of topics and then herd these topics into

of Web pages

your

cally.

list

to visit

first.

home

page

The secondary pages might

lead users to tertiary pages, cultural

TABLE

Web

12-1

and so on. Table 12-1 helps organize the pages of a simple

agri

site.

A Portion

of a

Web Page

Parent Page

Web Page

Not applicable

Home page

Planning Table

i

for a

Simple Agricultural

Web

Site

Contents

Purpose and audience

of site, navigator, search box,

engaging picture, and About Us

Home page

Summary

Fertilizers

tertiary

Summary

Grafts

tertiary

table of different grafting techniques, leading to

pages

Summary

Infections

table of various fertilizer categories, leading to

pages

table of various infections, leading to tertiary

pages pages

Pesticides

Graphic

Fertilizers

Organic

Table of organic fertilizers and relative efficacy

Inorganic

Table of inorganic fertilizers and relative efficacy

Infections

Citrus Canker

Summary

Nonbacterial

Table of nonbacterial infections

Web

Pick the Right

of various pests, leading to tertiary

of latest research; links to key sites

Technologies

Your plan should consider technological questions such as the following: •

What

parts of your

Web

site will

provide

information and what parts

static

dynamically generated? Static content looks the same to every

By contrast, dynamic content can vary per itor

•

is

(this

Who may

is

called personalization) or

•

What technology a

Web

access your

everyone, although

site?

some do

will

Most

visit,

technical

grows past even

Web

to evolve the

Web is

who

be

visit.

the vis-

wants to do.

sites

restrict access for security

you use

a small

visitor

will

on every

based on factors such as

what the

few pages, then no supporting technology

visitor

provide free access to

or financial reasons.

site? If a

Web

site

consists of only

Web site Web site becomes difficult.

necessary. However, as a

number of pages, maintaining

the

To untangle the mess, consider content-management software.

Web

Sites

> Plan Your

Web

Site

163

Home

Page: Specify Purpose and Audience

The home page at

any Web

site

and the two

The

first

and

its

is

the designated starting page for a

that follow provide guidance

order of business with any

is

In the

•

title

title

of your

home

Keep the

results.

In the top-level header

•

through an In the opening

•

pages.

and technical

sites

purpose of the

site

do not need

sites

a

should just blurt out the purpose

in the following three places:

page. Use the

appears in your browser's

engine

implementing. This chunk

to state clearly the

site, scientific

catchy slogan or a cute catchphrase. Instead, such

most important page

the

It is

to

on building home

home page

audience. Unlike a commercial

and audience

Web site.

and the one you should devote the most time

title

brief

title

HTML

tag to specify the

title.

The

banner, in browser bookmarks, and in search

— no longer than eight words.

on your home page. You

typically specify the top-level header

tag.

body

inside a

tag, but

For example, the following

text of it

your

might

HTML

home

page.

just as easily

The opening body

be inside a

text

typically

is

tag.

passage shows the start of an agricultural

Web

site:



Latest Citrus-Growing Research for Farmers

Latest Citrus-Growing Research for Farmers

This site details the latest agricultural research on growing oranges, lemons, and limes. We've built this site for professional citrus farmers, particularly those with agricultural degrees.

The

Title

Writing

and

a

good title

precise.

is

a difficult

balancing act because a good

Somehow, you must capture

the essence of your

title is

Web

simultaneously concise site in a

of words. As a rule of thumb, do not use more than eight words in a congratulating yourself on the slimmest possible eral

is

title,

remember

pretty worthless as well. For example, the following

title is

111 164

Web

Sites >

Home

Page: Specify Purpose and Audience

title.

that a

bare

minimum

However, before

title

that

is

too gen-

too general; based

on

the

limited information

it

presents, the

Web

site

could just as easily be for diabetics, doctors,

or researchers:

Artificial

Insulin Research

By contrast, the following Artificial

Title

title

precisely identifies the audience:

Insulin Research for Type B Diabetic Patients

and Search Engines

When displaying matching Web sites, search engines display the exact title embedded in your tag. Consequently, a precise title attracts appropriate visitors to

your

site.

Web

Sites >

Home

Page: Specify Purpose and Audience

165

Home

Pages: Engage the Reader's Imagination

Web

Surfing the

decide whether is

is

similar to cruising for a television show. In either case, potential viewers

new content

is

worthwhile

only a click away. (Rest assured that

Web

bors other

makes

its

sites that

handful of seconds since alternative content

World Wide Web almost

The moral:

cover similar territory to yours.)

a

certainly har-

good home page

case very quickly.

Presenting an eye-catching graphic

The key

page.

in a

this great big

is

to pick a graphic that

is

probably the best way to engage readers is

in a

home

appropriate for the audience. (See the next page

for details.)

Another more devious mechanism

—one only appropriate

mysteries that can only be answered by exploring the

because intelligent readers have trouble passing up

of

a

home

page shown

question on the

home

in Figure 12-1 features

page

Do you know the answers

How many rings does

•

What

•

Do

.

Why

nique

is

a challenge.

is

few

effective

For example, the portion

questions about Saturn. Notice that each

a hyperlink to the answer.

made

of?

is

Saturn lighter than water?

Engage

lay

readers by posing questions on the

scoff at this technique, thinking that effective

because

Remember

it

it

sounds

is

home

page.

a bit childish.

page and

>

Home

this techsite's

inappropriate for a serious academic

Web

, Sites

However,

probing the

gets users to leave the

that this technique

home

site.

Web

to pose a

other planets have rings'?

real content.

166

is

Saturn have?

are Saturn's rings

12-1

You may

—

This mechanism

to the following questions

.

FIGURE

is

for lay sites

Web site.

Pages: Engage the Reader's Imagination

start

Home A

Pages: Set the Tone

well-constructed

identity the for

Web

home

page should provide obvious visual clues enabling visitors to

tone immediately and to determine whether the

site's

them. In essence, setting the tone

text,

although setting the tone acts

site is

appropriate

similar to defining the audience explicitly through

is

at a

more emotional

level.

home pages devoted to the planet Saturn. For a Web site aimed at home page should feature a large, beautiful, color photo of the planet. By contrast, for a Web site aimed at planetary scientists, the home page might feature a graph or perhaps a map of magnetic fields on the surface. For example, consider

a lay audience, the

A Site for Technical Practitioners A serious Web site aimed at serious researchers page guidelines help •

Use

common

set that

requires a serious tone.

The following home

serious tone:

sans-serif fonts such as Arial or Verdana,

which are usually the

browser's default fonts anyway. Never use exotic fonts. Render text in black on a

white background. •

Provide an overtly technical illustration on the

•

Make

•

Provide

sure that text a fairly

high

home

on the home page contains

amount of information on

page.

at least

the

some

home

jargon.

page, although not to the

point of clutter.

A A

Site for a Lay

Audience

technical or scientific

Web

site

aimed

at a lay

audience requires a gentler, less-intimidating

foyer than a site for technical practitioners. For example, the

home

page for

a site that

explains asbestos to a lay audience should not display an X-ray of a diseased lung. nonscientists find science intimidating or humbling. Therefore, your

provide a comforting environment, following

list

provides

some

a

much

Provide

•

Provide a photograph that contains

ter, at least

waiting

room of a

Many

needs to

doctor's office.

The

few guidelines for setting the tone:

•

(Ideally, the

like the

home page

color. a

person should be smiling.

show

person interacting with the target technology. If

smiling

is

inappropriate for the subject mat-

the person in apparent mastery over the technology.)

•

Do

•

Provide plenty of white space in the design, giving the

not use jargon.

Web

Sites

home

>

page

Home

a relaxed, airy feel.

Pages: Set the Tone

167

Page Templates Most of the Web pages within

a single large commercial Web site share the same layout. Web site for the online edition of a large newspaper might con90% of them might share the layout shown in Figure 12-2.

For example, although the

thousands of pages,

tain

Logo and top banner

Headline

,Navigatorl

Body

of article

iNavigatorN

FIGURE 12-2

Layout of a typical online newspaper.

To implement

a consistent layout

a

page template.

a

Web

site

A

site

into a

class

of Web pages.

When

uses page templates consistently, readers quickly learn where the content

where the navigational aids

A

such as the one shown in Figure 12-2, you must define

page template defines the layout elements of a

are,

and even where

to avoid looking (at the ads,

I

is,

suppose).

without page templates forces visitors to regain their bearings whenever they step

new Web

page.

A Web site composed without

page templates

is

like a

program whose

graphical user interface changes with every use.

Page templates are not just for site

with only

plate,

when

You can use

a

dozen

applied to

Web all

large,

commercial

pages should

pages in a

Web

a variety of techniques to

still

Web

rely

site, will

on

sites.

Even a modest, technical

a page template.

give a site a far

A

more

Web

simple page tem-

professional look.

implement page templates. The most sophisticated

page template mechanisms are built into enterprise content-management software. Such software enforces the use of page templates, making create different-looking

168

Web

Sites

Web

pages.

> Page Templates

it

impossible for renegade cowboys to

Figure 12-3 shows two different

FIGURE 12-3

Two

different

A

Set of Page Templates

A

large

Web

Web

pages created from the same page template.

Web pages rendered

site typically

with the

same page

template.

contains multiple page templates. Each page template

represents a different variety of pages. For example, you might have one page

template for lab reports and another page template for somewhat more casually presented information. However, even all

the page templates usually share

in

Web

sites that

use multiple page templates,

some common themes.

For example,

templates might share the logo of the organization that supports the

Web

Sites

Web

all

page

site.

> Page Templates

169

.

Navigators and Search Boxes

Each page

That

much

in a

Web site

should provide

a

pathway

to reach

all

other pages in your

Web site.

not to say that each page must provide a one-click link to every other page. (That

is

navigational baggage

should provide in just a

few

a clear

clicks.

would crush any

large

Web

site.)

pathway allowing readers to move

The most popular

to

Nevertheless, each page

any other page

strategies for navigation within a

in the

Web

Web

site

site are as

follows:

•

navigator

•

search box

Whichever method you choose, be consistent about search

box appears

should appear

in the top-right

in the top-right

corner of your

their placement. For

home

page, then that

corner of every page in your

Web

site.

example,

if a

same search box

Don't make readers

hunt for navigational devices.

Navigators

A

navigator

is

a

list

of multiple hyperlinks (and nothing but hyperlinks) that helps readers

get to the desired page. For example, consider the simple navigator in the agricultural site

shown

Web

in Figure 12-4.

Soil ;

I

:

have a high clay content to encourage rapid drainage Soil that is too heavy will keep moisture in and enhance the formation of various kinds of molds that can Soil should

damage

The pH :

I

!

I

FIGURE 12-4

The

fruit

should be neutral, just between 6 5 and 7 5 The

soil in central

Florida

is naturally

alkaline

due

formations of limestone just below the top

need to add some magnesium decrease the pH

left

The navigator should

side of this

Web page

or

to large

soil,

bloodmeal

so you

may

to the soil

I

contains a simple navigator.

clearly distinguish the current page. For example, since Soi

current page, notice that the navigator does not display a hyperlink for Soi

170

Web

Sites

> Navigators and Search Boxes

1

1

is

the

Notice that the anchor text (for example, link in Figure 12-4

is

word, but one word

CI imate, Ferti

own

only one word long. Your

and so on)

for each hyper-

more than one

certainly the ideal.

is

The navigator

for a simple

However, once

a

Web site

become

izers,

1

navigator can contain

Web

site

contains

can contain

more than

a pointer to

every page in the

Web

ungainly. (By the way, try to avoid forcing readers to scroll

page

starts to

see a

submerged part of

For example,

a multilevel navigator.

To keep

the navigator.)

choices should appear, as

shown

if

site.

15 or so pages, a navigator with links to every

a navigator at a

manageable

size,

down

to

consider

the reader clicks Climate, appropriate additional

in Figure 12-5.

Temperature Although most people equate citrus trees with the tropics, citrus trees are actually more comfortable in the subtropics Extremely hot or extremely cold temperatures will

damage

Because most

citrus trees

peninsula, surrounded on three sides by

of Florida is a

warm oceans, the

climate rarely enters into the extreme range However, trees planted too close to the panhandle must endure

temperatures outside the citrus comfort range Recent climatological research presented on this page identifies the frequency of extreme temperatures in 12 actual and potential citrus-growing sites in Florida

Beyond

the proximity to

plays a large role

in

warm ocean water,

clearly latitude

climate, particularly with regard to

hard frosts

FIGURE 12-5

A

two-level navigator, which

is

typically

implemented through JavaScript.

Search Boxes Instead of searching for the right hyperlink in a into a search

box and

let

it

loving search boxes but end up frustrated with generate. Nevertheless,

which

site(s) will

if

you do implement

menu

or navigator, users love to type text

To be more

find the right link.

precise,

most readers

them because of the spurious

a search box,

be searched. The simple phrase Search

make is

start off

links they

sure that you clearly define

no longer

clear;

it

could

mean

Search this Site Only, Search the Entire Internet, or anything in between. For example, Figure 12-6 shows a clear search box.

Enter a phrase

FIGURE 12-6

diabetes research

tor

,-,.!' [hiiWik^ilt-

doctors

An unambiguous search

box.

Web

Sites

> Navigators and Search Boxes

171

Hyperlinks

Body

in

Text

During the Web's infancy, many users thought

Web

Nowadays,

most out of hyperlinks within body

to get the

that hyperlinks

were

its

coolest feature.

chunk explores how

users take this critical technology for granted. This text.

Hyperlinks Are Revolutionary

Hyperlinks represent a sea change True, hard-copy

which,

contrast,

how people search

for technical information.

hyperlinks, point readers to similar sources. However, unless readers

like

happened

in

books have long contained endnote citations and bibliographies,

to be in a

major

library,

access to cited works could be weeks away. By

modern scholars now complain when

a hyperlink forces

them

to wait

more

than ten seconds.

Click Here

Web

designers hate using the phrase click here as anchor text. For example, approximately

100% of Web To see

Web

designers believe that the following hyperlink looks amateurish:

Dr. Jill

Black's tutorial about eczema, click here

designers greatly prefer using the target

ple, the

following example omits

Dr. Jill

Once

click

it is

newcomers

as the

anchor

text.

For exam-

.

clearer to write a passage with click here than to adhere dogmatically

to the click here prohibition. In fact, ative

word or phrase

here altogether:

Black created a tutorial about eczema

in a while,

.

to the

Web

if

(yes, this

your

still

Web

site's

target audience includes

happens), then

click

here

is

many

rel-

often the least ambig-

uous choice.

QUANTUM LEAP In this

age

of

computer

viruses,

many

readers are justifiably nervous about clicking

hyperlinks unless they are sure of what they are getting hyperlink

in

your

Web

site

and

is

one), that user often

becomes suspicious about the

text should honestly

and accurately represent the target URL.

li 172

into.

Web

Sites

> Hyperlinks

in

Body

When

a user clicks a

transported to a surprising location (even a benign

Text

rest of

your

Web

site. All

anchor

The Right Number of Hyperlinks in Text Too many hyperlinks can confuse readers. For example, consider

the following hyperlink-

happy sentence:

Dr. Jill

Black a renowned dermatologist created a tu torial about eczema one ,

,

many common

The preceding sentence contains ers followed every

one of these,

six hyperlinks,

it

which

is

In addition, since hyperlinks are usually

reasonable rule of

thumb

is

to

.

an overwhelming density.

If

read-

could take them hours just to process that one sentence.

rendered

in the default

black-and-blue mixture takes on a striped appearance that

A

of

,

skin diseases that can be triggered through allergens or heredity

keep hyperlinks

one per sentence applied across any

down

entire page of text

to

blue color, the preceding

somewhat

is

difficult to read.

one per sentence, although even

would be way too many.

Default Blue Hyperlinks Are Best

By

default, browsers render hyperlinks in blue

easy to change this default; however, readers to slow

down

to figure out

A Separate Target Window When visitors follow hyperlinks, might arrive

at a

I

they typically

jump

same Web

further and further away from the original

Web

against

it.

Web

off the current

site,

text.

It is

fairly

Changing the default

what graphic notation represents

different part of the

this reason, the clever

and underline the anchor

recommend

but they

still

forces

a hyperlink.

Web

page. True, they

lose context

page, eventually waving

it

and

drift

good-bye. For

developer considers implementing hyperlinks so that the target

appears in a separate window. That way, visitors can stay on the current

Web

page while

exploring other hyperlinks.

Be careful how you make additional browser windows appear,

lest

you

trigger a

pop-up

blocker's wrath.

:

Web

Sites

> Hyperlinks

in

Body

Text

173

Secondary Pages As noted

secondary pages (that

earlier, all

to present a consistent format. This

is,

nonhome

chunk provides

a

pages) should use a page template

few suggestions about those second-

ary pages.

Keep Content of Each Page Relatively Brief Keep the amount of content on each Web page relatively brief. stated that users hate to scroll, so

Web

screen without a scrollbar. However, in the

accustomed to

last

Web

axiom

in a standard

fit

few years, users have gradually become

and the design prohibition against

vertical scrolling,

ended. Nevertheless, lengthy

In the 1990s, a design

pages should be short enough to

vertical scrollbars has

pages (beyond about four scrolled pages) are

still

frowned upon. For example, suppose you must convert this book into oper,

you would make

an entire chapter into

a

Web

Web

a single

Since content must be brief on each pages. Probably the best

this chapter). In addition,

Web

Web

site.

As

a

good Web devel-

page.

Web Pages

Associate Related

Web

a

page out of each one- or two-page chunk rather than putting

page. Since the

Web

not put Next buttons a specific order. For

way

Web

to

do

page,

this

is

you need through

to find a

way

you might provide See Also hyperlinks

is,

at the

by

its

nature, a random-access

it

would be appropriate

at the

bottom of each

medium, you would

bottom of pages unless each page

example,

to associate related

a navigator (described earlier in

is

truly

meant

generally

to be read in

to put Next buttons at the

bottom

of tutorial pages.

Keep Content Narrow Although users have become accustomed horizontally. (Note that

to scrolling vertically,

most modern mice provide

most users despise

a vertical scroll

zontal scroll wheel.) Furthermore, placing text in relatively narrow

read quickly. Therefore, the wise

Web

newspapers and keeps body

between 350 and 500

Graphics

—

text

scrolling

wheel but not a hori-

columns helps users

developer follows the same practice as most online

particularly high-resolution photos

—

pixels in width.

are often rather wide. Within a

Web page,

avoid displaying wide graphics that will force users to scroll horizontally. Instead, display a

scaled-down version of the graphic and provide readers with

the full version

up

in a separate

i 174

Web

Sites

> Secondary Pages

a

hyperlink that will pop

window. (Beware of pop-up blocks, though.)

Text

Web

in

Sites

Most of the

rules established in Section 2 of this

words, your

Web

book

content should consist of short,

also apply to

clear, active-voice

Web

pages. In other

sentences that use

Web is When creating content for the Web, the

vocabulary appropriate for the target audience. However, creating content for the not exactly

writing traditional documentation.

like

wise writer considers the following differences:

•

The

'em what you're going

"Tell

approach

less

is

valuable in

to

tell

'em what you told 'em"

'em... tell 'em... tell

Web writing

than in traditional writing.

Web visitors

fre-

quently don't have the patience to read introductions and seldom have the patience to read conclusions.

Web

visitors typically just

want

to dive straight into the entree,

skipping the appetizers and dessert. •

You have

range of media

a

effectively presented

tend to have

less

at

your disposal. Some kinds of information are more

through audio or video than through

text. In fact,

Web

visitors

patience for straight text than do readers of hard-copy documenta-

tion.

•

To handle

a

long block of text within a

- Use subheads

-

Start the

Web

page with a bulleted

- Make each element the page.

Web

page, consider the following approach:

to divide the long block of text into units.

in the bulleted

list.

list

a hyperlink,

The Web page skeleton shown

pointing to subheads within

in Figure 12-7 illustrates this

approach.

Citrus Canker Research This

page discusses recent research

n

•

!

:

_...•.

in citrus

canker, which

falls into

the following categories

.

ip.iead

Quarantine [Lengthy text goes here

]

Antibiotics [Lengthy text goes here

]

Disease Spread [Lengthy text goes here

FIGURE 12-7

]

Handling large blocks

of text

through bulleted

links

and subheads.

Web

Sites > Text in

Web

Sites

175

PDF versus HTML On

the Internet, the two

most

common document

HTML and

distribution formats are

PDF. Table 12-2 compares and contrasts these two formats.

TABLE

Comparing PDF and HTML documents

12-2

HTML

Question

PDF

Can the user change an

No. The user must

with the

live

Yes and no. The answer depends

on how the author has set up the

author's font choices.

document.

author's font

choices?

Can the author

Yes.

embed

embed

fonts?

The author can optionally fonts within a

PDF

No. The author cannot to

file

fonts within an

HTML

embed

file.

The

ensure that users can view the

author can, however, suggest

document

nate fonts to use

properly.

first

if

alter-

the author's

choice of fonts

is

not available

on the user's machine.

Does

When

No.

text

rejustify

when

the user resizes

the user resizes the

Yes (usually).

When

the user

Acrobat Reader window, text does

resizes the browser window, text

not

typically

rejustify.

does

rejustify.

a window?

When

the user resizes the

Does font size change when

Yes.

the user resizes

font size adjusts. Thus, fonts look

a

Acrobat Reader window, relatively small

window?

window Does

Yes.

this

is

PDF uses

cal

concept of

processor.

No.

When

the user resizes the

browser window, font size does not change.

when the viewing

small.

the traditional physi-

page metaphor,

format use the

virtual

just like a

word

No.

A user can scroll almost infidown a lengthy document

nitely

without encountering page breaks.

pages? pages look almost

No. Pages print

strange and

Do documents

Yes. Printed

print well?

exactly as they

uncontrollable ways.

directly

information on wide lines doesn't

do when printed from the author's word

get printed at

processor.

PDF documents look awfully similar to a trol

over the layout of each page, just

traditional book.

like

WYSIWYG

in

Sometimes

all.

PDF gives authors complete conprocessors. With HTML, the

word

author hands over some of the formatting power to the browser and some to the end

176

PDF

is

Web

Sites >

rigid;

HTML

is

flexible.

PDF versus HTML

user.

Should You Distribute PDF or In an ideal world,

some

all,

is

a lot

Many

HTML?

you would distribute documents

users prefer

PDF and some

prefer

HTML.

in both

PDF and HTML

However, distributing

in

format. After

both formats

of work.

users

still

prefer hard-copy

documentation

to soft-copy

documentation.

A

few of

these users have such a strong preference that they print out online documentation. Since

PDF documents

the hard-copy version of

of

HTML documents,

The average author would convert ever, that file.

looks

a

better than the hard-copy version

HTML files; how-

lengthy manual into a set of multiple

same average author would convert

The PDF version

much

score a point for PDF.

that

same lengthy manual

often contains several orders of magnitude

more

into a single

bytes than

PDF

one

HTML file. Consequently, if your users access online documentation over a low-bandwidth network, HTML a better choice. is

Finally,

some

documents from devices (such

users read

most

as

cell

phones) that cannot

display PDF. However, a rather extraordinary collection of devices (not just traditional

HTML.

computers) can display some form of

Programs to Handle PDF

Adobe invented PDF; however, PDF

is

an open specification, and

some

other vendors

have created software products for interacting with PDF. Nevertheless, the key

PDF

software programs for interacting with

Acrobat Reader

is

a

are

program that displays PDF

still

made

files.

It

is

by Adobe. freeware, available from

www.adobe.com. Many modern computers preinstall Acrobat Reader. Furthermore, an Acrobat Reader plug-in

Acrobat

Distiller is a

lets

users view

PDF

files directly in their

program that converts documents

to PDF.

browsers.

The

full-strength

version of Acrobat Distiller (generally marketed within a larger package called

Acrobat Professional) (including, ironically,

lets

authors convert just about any kind of document

HTML

files) into

PDF.

Some word

processors

embed

a reduced-

strength version of Acrobat Distiller that enables conversion of only certain kinds of

documents

into PDF.

make products that enable authors and others PDF file, it is generally far smarter source document, and then regenerate the PDF file. Adobe (and

files.

others) also

However, instead of editing the

Web

Sites >

to edit

PDF

to edit the

PDF versus HTML

177

Frequently Asked Questions (FAQs)

This chunk details frequently asked questions (FAQs), which are a staple of technical

Web

sites.

What is A FAQ

a

—

FAQ?

as

addition to didn't

you probably know

Web

sites,

you read the

Why do many Most readers

—

FAQ

bunch of questions and

consists of a

newsgroup snobs

love to use

FAQs

to intimidate

their answers. In

newcomers.

(

Why

before posting that question?)

readers hate FAQs?

like

the concept of FAQs; however, the actual

FAQs

often leave something to

be desired. Usually, readers are angry because FAQs don't contain their questions.

How

should you create a FAQ?

The technique

for creating a

FAQ

is

commonly

of the most

—

simplicity itself

just

1.

Gather up a

2.

Provide answers for each of them.

3.

Organize groups of related questions into sections.

4.

Optionally, provide a search

How do you

list

gather up a

list

do

the following:

asked questions.

mechanism

to help readers find the best-fit question.

of questions?

For product-related FAQs, just ask your customer-support organization, since they usually

keep records of

all

the questions that customers ask. For science or general technology

FAQs, questions posed on newsgroups and electronic bulletin boards often provide good sources of questions.

Can you make up your own questions? Absolutely. Don't rely completely

on questions

that others have already asked.

Sometimes

people are too embarrassed to ask questions that they think are too basic. You, the writer,

should make up some of the questions. The best FAQs successfully anticipate readers' questions.

What questions should you ask The

first

first?

question should always explain the purpose of the FAQ. The next few questions

should summarize the product or technology. In essence, you should write an introduction in

Q-and-A format.

1 178

Web

Sites > Frequently

Asked Questions (FAQs)

Should you include every possible question No. ter

A question asked only once does the FAQ with arcane questions.

What

in

a

FAQ?

not constitute a frequently asked question. Don't clut-

the key to answering questions?

is

Be concise; answer the question than three paragraphs.

If

in a

paragraph,

an answer can't

fit

if

possible.

in three

Never write an answer longer

paragraphs,

split

the question into

two or three narrower questions. Don't try to explain the whole world to other related

What

formal tone in FAQs and will appreciate a casual, down-to-earth

a

approach. Writers can often

Can you place graphics

Is

—

in

in

a

their hair

down

in a

FAQ.

answers?

FAQ?

but remember that

it is

notoriously difficult to create a response that everyone in a

humorous.

diverse audience will find

If

let

readers love graphics.

humor okay

Yes,

each answer; create hyperlinks and cross-references

the proper tone for answers?

is

Readers do not expect

Yes

in

answers that might already have the goods.

grouping questions, how many questions should you place

Keep groups of questions get too long, subdivide

fairly

them

small (fewer than 10 questions).

in

each group?

When

groups of questions

into narrower categories.

How do you make a FAQ searchable? large Web sites provide automated indexing, so a FAQ placed in such a Web site will automatically be searchable. If your FAQ does not have the benefit of automated indexing, consider placing the entire FAQ in one physical file. Readers can then invoke their browser's Find menu to search for key words. The only problem with this approach is that a single file FAQ particularly one with a lot of graphics might take an annoyingly long time to Most

—

—

download. To get around answers) the

list

in

one physical

this

file.

problem, consider placing only the questions (not the

Then, place each answer

of questions quickly, since the question

file is

in a separate

file.

Users can download

usually relatively small

and

typically

does not contain graphics.

— Web

Sites

.....

> Frequently Asked Questions (FAQs)

H'^ 179

Summary The home page

is

of

the

Web

Sites

most important page

you should expend the most energy on.

your technical

in

When

reviewing your

Web site and the one that home page, ask yourself the

following questions:

•

Does the home page

•

Does the home page engage the

clearly explain the

•

Does the home page

•

Does the home page provide

purpose of and audience for the

reader's imagination

site?

and encourage exploration?

establish the tone for the site?

mechanism

a

and searching the

for navigating

rest

of

the site?

When •

reviewing your secondary pages, ask yourself the following questions: Is

the writing accurate, concise, and audience appropriate?

to the best practices highlighted in Section 2 of this

common

•

Do

•

Does each secondary page contain

•

Is

the secondary pages share a

the

body

text

layout, enforced

a descriptive top-level

on any secondary page longer than four

ondary page should be longer than four pages. long, divide

When

Does your Web

Web

site,

site truly live

Can

visitors easily find their

•

Can

visitors find

up

your

site

>

title?

scrollable pages?

you find

a

Web

No

page that

is

sec-

too

scroll horizontally.

ask yourself the following questions: to the

purpose and intended audience stated by the

way around

from

t Sites

conform

through page templates?

header and

page?

•

Web

the writing

into multiple pages.

reviewing your entire

home

180

If

Are any pages too wide? Pages shouldn't force users to

•

•

it

Does

book?

Summary

of

Web

Sites

a search

the different pages in your

engine?

site?

CHAPTER

13

Proposals

proposal

develop

is

a

a

do something

written request to

program... you

name

it

—

—perform

research, start a

company,

exchange for money or other resources.

in

The

Proposals are a large part of the academic, research, and business worlds.

lowing are some of the more

common

fol-

kinds of proposals that engineers and scientists

write:

Research proposals. These are requests to organizations such as the National Science

•

Foundation or European Organization for Nuclear Research (CERN) to fund scientific

research. Research proposals are the

and sciences

economic

lifeblood of

many

universities

labs.

Business plans. These are requests to venture capitalists (VCs), banks, or other

•

investment houses to fund or expand a company.

Book

•

At

first

proposals. These are requests to a publisher to fund a book.

glance, this

common. Beyond and

bios), the

may seem

like a disparate

group; however,

all

proposals have

purpose of any proposal

to

is

convince the target audience that you are

exactly the right choice for an investment. Therefore, understanding

ence wants

some

a lot in

the obvious similarities in content (for example, cover letters, abstracts,

is critical.

This chapter details

all

what your

three types of proposals but

first

target audi-

explains

general proposal-writing concepts.

Are Proposals Truly Important? Engineers

who

who

believe that proposals are unimportant are as successful as actors

think that physical appearance

proposals,

money and

insist that

cup

dry,

remain

overrated. will

If

you learn

to write effective

flow out of the tap and into your cup.

If

good ideas are more important than good proposals, your and you will turn bitter. The goal for this chapter is to improve

you stubbornly will

is

other resources

your chances of getting proposals accepted.

Proposals

181

The Proposal before the Proposal Before writing a formal proposal, your team should produce a preproposal, which

summary (oral or written) since team members will likely

brief, clear

of the project. Producing

nizing

have divergent ideas

important that the team reach consensus

become

fluent in the preproposal

Creating formal proposals

is

investing this kind of effort,

example, prior to writing in a short

a

and be prepared

you

first

to pitch

it

If

a

is

often agoit is

of the team should

on short

affair for

book proposal, you should present

formal book proposal.

posal unless they've

member

need to get some sort of

typically

is

at this stage. Nevertheless,

Each

a time-consuming, agonizing

conversation with a publisher.

will sanction a

fairly early.

one page

this

notice.

most

writers. Before

affirmation. For

initial

the basic ideas for the

book

the publisher likes the preproposal, he or she

Some

publishers won't even read a formal

book pro-

read or heard a preproposal.

Elevator Speeches

A preproposal

for a

business plan typically takes the form of an elevator speech.

Imagine that you find yourself standing next to a venture capitalist (VC) elevator.

Can you

pitch a compelling business plan before the

VC

in

an

gets off? You only

have 60 seconds, so here's what to say: •

Introduce yourself and state your credentials.

(Hi,

I'm

Kay Linda, president

of

Dexco Unlimited.) •

Describe the problem that your company plans to solve. To put describe the potential market. (Did you suffers from

some form

know

that

10%

it

another way,

of the adult population

of heartburn?) Ideally, you should get the

VC

to identify

with the problem. •

Describe your company's amazing solution to the problem. over-the-counter antacid that reduces acid 12 times

more

(I've

developed an

effectively than

calcium carbonate.) •

numbers and percentages how much money you need it. (We need four million dollars, of which approximately 50% will go into completing research, 30% will go into marketing and distribution, 10% will go into fabrication, and 10% will cover Explain

in

nice round

and what you plan

salaries

VCs who

to

and expenses

do with

for

18 months.)

leave the office for a while often return to a voice mailbox

speeches. The best speeches convince VCs that a market with anything business related, to

remember

full of

elevator

waiting to be tapped. As

to focus on the financial part of things

minimize the technical wizardry.

li 182

is

Proposals > The Proposal before the Proposal

and

Adherence

Template

to the Proposal

Most proposal committees provide standard proposal templates or follow the proposal guidelines as closely as possible. plete 132 sections

complete

all

—

What you

is

a

Do not add extra sections. Do

wonderful thing, but

exactly does following the template

to provide the

achiever,

you think

names of

mean?

tells

to

to

com-

Do

not ignore

it.

Well, suppose the proposal template asks

three customers currently using your product. As an over-

"Heck,

to yourself,

you

You need

— then you must

not delete sections.

this isn't the place for

if

three customers are good, then four or five ought

to be even better." In this case, though, three really

the template

guidelines.

the proposal requires that you

half of them clearly for worthless bureaucratic reasons

132 sections.

sections. Creativity

If

is

better than four or five. Similarly,

if

keep the "Technical Background" section under 250 words, then

don't feel that providing 500 words

twice as good.

is

Gantt chart, then you must provide

a

If

the

Gantt chart even

if

"Work

Plan" section requires a

you already have

much

a

better

schedule inside a spreasheet.

The Consequences

of

Suppose you are

member

a

Not Following the Template of the

proposal review committee. Your committee must

distribute a ten-million-euro grant for a four-year project.

containing brilliant ideas, but only one of picks the conformant one.

Why? The winning

follow the committee's rules.

Two proposals

arrive,

both

follows the template. Your committee

proposal team proved a willingness to

The losing team did

intention of entering into a four-year

work

them

not.

The committee had no

agreement with a team that would be

difficult to

with.

Proposal templates are not always

clear.

What

if

you don't understand some aspect of the

template? You need only ask. For research proposals, the reviewing committee typically designates a program

manager whose duties include

talking with submitters.

It is

less

embarrassing to ask questions up front than to submit a confused proposal. In addition, the proposal review committee often publishes copies of successful proposals. Emulate the

winners.

QUANTUM LEAP What proposal review committees see in a proposal is what they the proposer. Make sure that your proposal is tidy and typo free.

think they'll get

in

Proposals > Adherence to the Proposal Template

183

Proposal Element: Cover Letters

Most proposals require was sent or

so.

Where

cover

a

to the recipient.

A

appropriate,

letter,

which introduces the proposal and explains why

cover letter should be short

—generally only

should remind the reader of previous interactions.

it

priate (for example, in a business plan's cover letter), consider providing a date," identifying

Example

13-1

EXAMPLE 13-1

what

shows

a

will

happen

sample cover

Sample Cover

if

If

appro-

"drop-dead

the recipient does not respond by a certain date.

letter for a

business plan.

Letter

Attn. Barney Rutherford

Dexco Unlimited 317 Kenyon Ave.

Palo Alto, CA 94306

1-650-555-1212 br@dexcounl .com

May

1,

2005

Monadnock Investments 25 Hewitt St.

Cambridge, MA 02139 Attn: Janet Mertrie

Dear Ms. Mertrie, When we met last month in Atlanta at EntCon, you asked me to prepare

a

formal

business plan for an initial round of funding at Dexco Unlimited. I'm pleased to

provide the attached business plan, which explains Dexco Unlimited and why we'd like additional funding. As you probably recall, Dexco Unlimited has created a prototype for a new

enterprise software application that provides personalized human resources information. We believe that our application will dramatically reduce the total cost of ownership for small and medium-sized enterprises and compete effectively against existing firms in this space. Dexco Unlimited is delighted to offer this initial funding opportunity exclusively to Monadnock Investments.

If

Monadnock Investments does not respond by June

1,

2005, Dexco Unlimited will present this business plan to other potential

investors.

If

I

can answer any questions, please do not hesitate to contact me

directly.

Sincerely, Barney Rutherford

III 184

Proposals > Proposal Element: Cover Letters

it

three paragraphs

Proposal Element: Biographies

Proposals require a short biography (bio) of

When

curriculum vitaes (CVs) attached.

all

the principals, possibly with resumes or

writing a biography,

remember

that the goal

is

to

convince your target audience that you are exactly the right person to receive the grant. Unfortunately,

many

people find writing a bio one of the most daunting parts of the entire

proposal writing process, and are scared off by the following two conflicting thoughts:

Let

•

My

•

It

background

isn't right

me end

isn't

fancy enough to impress the proposal reviewers.

to brag.

the conflict for

you

—

it is

not only right to brag,

detrimental to think of this as bragging; instead, think of

chances of winning a proposal competition. Besides, sure that everything in your bio

is

100%

true.

Every

proposal reviewers do a check. Lying on your bio

is

it

it

it is

as

essential. In fact,

ain't braggin' if

fact

it is

optimizing your team's it's

make

true, so

on your bio must pan out

one of the quickest ways

if

the

to eliminate

yourself from contention.

Half-Lies

Don't write bios that are technically true but misleading. For example, suppose that

you played an administrative

role

on a team that made a major breakthrough. Your

bio should not vaguely describe yourself as being a

your bio should describe your specific

role,

"member

of the

team." Instead,

such as "administrative assistant on the

team."

Take

a

who have succeeded common? Is it a shining

look at the bios of people

What do

these bios have in

experience?

Is it

with the proposal review committee. education?

Is it

technical leadership

experience running small businesses? Did previous winners emphasize

their publications?

Experienced people often have trouble deciding what to emphasize in use the

same stock biography

for each proposal; cater

consider an experienced technologist

who

is

it

a short bio.

Don't

for each audience. For example,

creating a business plan

aimed

at

venture cap-

III. Proposals > Proposal Element: Biographies

185

italists.

The

goal of venture capitalists

phy would be suitable because

to

is

make money.

Therefore, the following biogra-

emphasizes management experience:

it

Biography of Rajendra Priyadarshan (appropriate for a business plan) Rajendra Priyadarshan has managed software organizations for the

last eight years.

For the last four years, Rajendra has served as the director of engineering at Dexco

manages a staff of 23 and an annual budget of over three million team produces two major and four minor product releases annually. Before coming to Dexco, Rajendra managed a QA team for four years at Carambola Software; during this period, the company earned a J. D. Power quality Unlimited, where he

dollars. His engineering

award. Rajendra also has worked at a variety of other organizations including MIT,

and Prime Computer. He holds an

Digital,

MBA

computer science from Rensselaer Polytechnic

On

the other hand,

technology,

it

if

Rajendra needed

would be wiser

gerial experience. In fact, too

Rajendra

is

to

a

biography for

emphasize

much

from MIT's Sloan School and a BS

in

Institute.

literary

a

book proposal on

a particular

and technical experience over mana-

managerial experience might suggest to reviewers that

out of touch with technology. Consider the following biography, attached to

a

proposal to write a book on software engineering in the Java programming language. This

biography aims to convince the target audience that he has the appropriate experience to write a successful book. Notice lication

how

this

biography begins by emphasizing Rajendra's pub-

and technical experience.

Biography of Rajendra Priyadarshan (appropriate for a book proposal) Rajendra Priyadarshan writes the popular "From the Trenches" column for Software Engineering Monthly. He has led teams of Java programmers on enterprise software applications since 1995. With

more than 20 years high-tech experience

at

companies

such as Dexco Unlimited and Carambola Software, Rajendra carries a wealth writing,

programming, and management experience. He holds an

Sloan School and a

BS

in

MBA

of

from MIT's

computer science from Renssalear Polytechnic

Institute.

QUANTUM LEAP

Some

business plans now include bios not only

of principals but also of the

pany's key consultants. Attaching your company's to a business plan.

IE* 186

Proposals > Proposal Element: Biographies

name

to a "star" often

com-

adds clout

Proposal Element: Abstracts

Nearly

proposals require an abstract or summary.

all

mary of your 1.

An

abstract

is

a highly concise

sum-

proposal. Organize abstracts as follows:

Begin with a strong sentence that summarizes the entire proposal. The sentence

should identify exactly what you want and 2.

Identify the

3.

Explain

Capturing

all

how your team this

why you want

it.

problem you are researching or the market need.

information

sary, reread Section 2

of

this

will solve this

in a

book

problem or meet

small space

is

a tall order.

this

Every word counts.

on keeping

for helpful hints

market need.

it

If

neces-

short. For example, con-

sider the following abstract for a research proposal:

Abstract

We

request a grant of $2.85 million to fabricate,

destressing systems

3 or higher),

30%

in

of all

houses within two miles

and

install,

hurricane-prone coastal zones.

In

test

1,400 roof

major hurricanes (category

of the coast incur significant

damage. Hurricane Andrew (1992) alone caused $30 billion in property damage, primarily to single-family structures. High winds cause huge pressure structural

differentials

between various parts

damage. Our team has developed

of a roof,

which can lead to catastrophic roof

a prototype for a

new

roof de-stressing system.

This system uses aerodynamic principles to shunt high winds away from roofs. This

system has proven highly effective

and

is

now ready

in

computer simulations and wind-tunnel

for real-world testing.

coastal zones with

We

tests

propose identifying 56 hurricane-prone

new construction and placing 25

test devices in

each zone.

In the preceding abstract, note the following:

•

The opening sentence reason. Reviewers

what the proposal •

The next

identifies the

who only is

read the

amount of the first

request ($2.85 million) and the

sentence would probably have a decent idea

about.

three sentences demonstrate an understanding of the

problem by

stating

several numerical facts. •

The concluding four sentences

state a solution to the

problem and

offer

suring preliminary evidence (computer simulations and wind-tunnel final

sentence summarizes the

test

some

tests).

reas-

The

methodology.

Proposals > Proposal Element: Abstracts

187

Proposal Element: Contingency Plans

By

their nature, proposals are glass-half-full sorts of

intending to

fail.

documents.

However, unbridled optimism hardly matches

new

research projects produce important breakthroughs, most years, is

and publishers

not a secret

lose

money on

to

is

writes a proposal

After

businesses

all,

fail

very few

after a

few

the majority of technical books they publish. Failure

—the people reviewing proposals

rarely cover failure. This practice

No one reality.

are certainly aware of

almost superstitious, as

if

it

—

mentioning

yet proposals

failure will lead

it.

In certain kinds of proposals, will

you should describe possible

pharmaceutical. The following proposal should please

committee because

We

expect phase

it

will

a research

prevent funding 18 months of worthless experimentation:

1 clinical

acne scarring. Although

testing to demonstrate significant reductions

this testing will last

preliminary results after only 6 months.

we will halt resources on improving Cream B. effective as expected,

Now

and explain how you

failures

proposal on a new members of the proposal review

handle them. For example, consider an excerpt from

If

24 months, we expect

Cream A

the clinical

trial

is

to

long-term

in

have valuable

proving less than

70%

as

on Cream A and focus our

consider a portion of a business plan that describes an alternate pricing policy based

on information

that cannot be

known

in

advance. Notice that the following passage

describes the alternate pricing policy as a contingency rather than as a response to a possible failure:

Since

we

are targeting Fortune

500 customers, we plan

exclusively through flat-fee site licenses. However, significant opportunities in in

year

2.

If

if

to sell the software

our sales force uncovers

medium-sized companies, we

a market for medium-sized

will alter

companies develops, we

the pricing policy

will offer

per-server

licensing on a subset version of the base product.

Describing failure

chance to do

it

is

not appropriate for

right.

Book

all

proposals. In

some

situations,

publishers, for example, generally won't

unsuccessful book. Nevertheless, since books usually take

at least a

let

you only

get

year to write, consider

describing possible mid-course corrections should the technology change while the is

being written.

li 188

Proposals > Proposal Element: Contingency Plans

one

you rewrite an

book

Proposals for Revolutionary Ideas

and engineers often dream up improvements

Scientists

and products. Proposals a receptive audience.

that explain

However,

at

how

to existing theories, technologies,

improve an existing technology usually find

to

some point

in

your

career,

you

are

bound

dream up

to

something wonderfully new and revolutionary. Unfortunately, revolutionary ideas are usually the

hardest to

ple are actually

From

world where we are exhorted to think outside the box, few peo-

for

doing

so.

the perspective of your audience (proposal reviewers), revolutionary proposals are

risky. In a

and how

business plan, reviewers worry about

it

would be marketed. Therefore, an

on minimizing •

In a

sell.

rewarded

the appearance of risk.

Compare certain

who would buy this

revolutionary product

effective revolutionary proposal

The following

list

must focus

offers a few suggestions:

and

aspects of the idea with concepts that are stable

successful. For

example, although your product might be revolutionary, explain that your pricing

model •

is

naturally •

just like Microsoft's.

Inoculate your proposal from reviewer skepticism. Answer the questions that will

come

to

mind.

Portray yourself as a down-to-earth, well-organized, focused individual. Don't portray yourself as a creative dreamer.

don't have the organizational •

Many

skills to

reviewers fear that highly creative people

bring the dream to

reality.

Avoid describing the idea as revolutionary. Instead, build your case and reviewer

come

let

the

to that conclusion.

For example, consider the following passage from

a

business plan:

Technical Background (for a revolutionary idea)

Our research team can predict commodity prices approximately two hours advance.

Many people have gone broke making

years of extensive data to back

Our team consists

of four

it

this claim; however,

in

we have

three

up.

PhD mathematicians and

a commodities trader.

We

have

methodically developed pricing formulas based on over 150 parameters. Our team

has gradually refined the weightings

of

each

of the

parameters to yield accurate

predictive formulas for three different commodities.

JUL Proposals > Proposals for Revolutionary Ideas

189

Research Proposals

Scientists in the states a

academic world submit proposals to perform research.

problem and your solution

to

it.

Good

A research proposal

proposals succinctly state the problem and

provide a more comprehensive solution. The competition to write effective proposals scary since a good grant can

well-endowed posal writer

a career. If

money

for grant

a dedicated,

is

against

experienced pro-

staff.

Understanding the Audience The people reviewing research proposals cases,

you are competing

be aware that most of them already have

labs,

on

make

are almost always scientists in

your

field. (In

some

an interdisciplinary team reviews proposals.) Each proposal review committee

includes one leader.

Committees

manager

typically hire a project

(often, a nonscientist),

interfacing with submitters. Feel free to ask the project

manager

whose duties include

for bios of the people

who

review your proposal.

will

Strategy I

hate to start with a negative, but

it is

useful to consider

why

research proposals get

rejected. Possible reasons for rejection include the following:

•

The proposed

research did not impress the committee; in other words, the

tee just didn't think the results

would be

•

The committee wasn't impressed with

•

The proposal was for Scientists

The following •

and

strategies

the proposer's credentials.

proposer had read, Spring Into Technical Writing

fuzzy. (If only the Engineers...

commit-

that valuable.

)

should improve your odds of acceptance:

Excite your reviewers.

Make

sure that your proposal conveys your

about doing the research. The committee reads

many dull

own

proposals;

excitement

make your

pro-

posal sparkle. •

Ally yourself with

someone who

will

to be blind to this sort of thing, but likely to

•

Write

turn over

clearly.

a well-written

money

to

impress the committee.

let's

face

someone with

The writing in most proposals document

that clearly defines

it

a track record than to is

of

this

book and

li 190

Proposals > Research Proposals

you'll

is

ought

much more

an unknown.

generally rather cloudy. By submitting

your proposed research, you might

shock the review committee into giving you money. in Section 2

Ideally, science

— the review committee

just

Just follow the rules identified

have a huge head

start.

Write concisely. For example, the National Science Foundation (NSF) requires that

•

proposals be no longer than 15 pages.

Make

•

a case for yourself. Your knowledge of the literature

should convince reviewers that you are the best person

and your experience

in the

world to do

this

research.

Contents of a Research Proposal

Many

review committees provide an extensive template; others provide extensive guide-

lines but expect

you

to figure out the details within those guidelines.

As always, proposals

previously accepted by your target committee are the best teachers, so read some.

Research proposals typically contain

•

cover sheet or cover letter

•

abstract or project

•

table of contents

•

project description,

some

subset of the following items:

summary

which should include

at least

the following:

- significance statement - objectives and hypothesis - experimental design and methods •

bios

•

schedule

•

budget, which in

The

is

often quite detailed

order to justify the

project description

is

the heart of every research proposal.

explain what you plan to do, in

your

field.

and might contain elements of a business plan

money

why

it is

The next few chunks

important, and

how

it

You have

compares

a

few minutes to

to other research

detail the key aspects of a project description.

JIM Proposals > Research Proposals

191

Research Proposals: Significance Statements

The

significance statement

important. Don't explain research

a

is

why

would be important

one- or two-page explanation of

the research

is

why your

research

is

important to you. Instead, figure out why the

committee. Read the committee's mission statement

to the

or template carefully. Committees funded by government organizations might require that

some

research proposals further little

do with your

to

The following

political need.

Their idea of importance

(fictitious) significance

statement

is

aimed

at a (fictitious)

agency that has previously funded projects to improve public

One

may have

very

idea of pure science.

statements

tactic for significance

is

to start general

government

safety.

and gradually

get

more

specific.

For example, the following sample starts with a broad statement (hurricanes cause casualties),

moves down

to the reason (poor predictions caused

moves further down

by imperfect technology), and

to the specifics of this project (our solution

improves predictions).

Significance Statement (sample)

1900 caused approximately 10,000 deaths, and the

The great Galveston hurricane

of

Lake Okeechobee hurricane

1928 caused over 1,800 deaths. Fortunately, as

of

forecasting skills have improved, the

Andrew

For example, Hurricane

of

number

of casualties

has dropped dramatically

1992 caused fewer than 30 deaths despite being

stronger than the 1900 and 1928 storms. Nevertheless, even a single casualty from a

hurricane

A

is

too great.

large part of

modern

casualties are caused by the "boy-who-cried-wolf"

phenomenon. When forecasters issue an evacuation order and the storm misses, residents stop taking evacuation errors seriously. The next storm thus causes even more casualties. Superior predictions will eliminate this phenomenon. The National Hurricane Center (NHC) currently bases predictions on programs (NOGAPS, GFS, BAM, UKMET, and GFDL). least

100 miles

in

errors

3

All of

over a 72-hour forecast period and over

over a 120-hour forecast period. These programs are generation of forecasting tools; however, they

still

78%

five

diagnostic

these programs average at

better

6

300 miles

in

errors

than the previous

have relatively wide margins

of

error.

We

have developed a prototype for a program that

within two years.

When

yields hindcast accuracy

a.

citation

b.

citation

will

cut forecast errors

20%

better than current

NHC

models.

I

192

in half

working with preliminary data, our current prototype already

Proposals > Research Proposals: Significance Statements

Research Proposals: Objectives and Hypotheses

The

project description should include a statement of your project's objectives. In other

words,

if all

goes well with the project, what do you hope to produce? For example, the

following sample "Objectives" section concisely identifies the desired results.

Objectives (sample)

We aim

to

develop a hurricane forecasting program that

levels

shown

TABLE

1

in

Mean

Table

cut forecast errors to the

will

1.

Forecasting Errors: A comparison

Current Forecasting Programs

72-Hour Mean Error

120-Hour Mean Error

(in miles)

(in

100

300

Our Forecasting Program

in

Two Years

50

125

Our Forecasting Program

in

Four Years

25

85

Your objectives should be subtle fallacy

The

in the

crystal clear

and contain no

miles)

logical fallacies.

(Can you spot the

preceding "Objectives" section?)

project description should also contain

one or more hypotheses. As with any

research,

your hypotheses should be provable. Unless the template permits a tremendous amount of detail (which

is

unlikely),

omit any secondary or

you should describe only one or two primary hypotheses and

tertiary hypotheses. For

example, consider the following:

Hypothesis (sample)

Most current programs forecast motion by calculating the

fluid forces that the

surrounding environment exerts on the hurricane and weighting the results with climatology. of the

We

hypothesize that

it

is

more accurate

to study not only the influence

environment on the hurricane but also the influence

surrounding environment. Our secondary hypothesis

is

of the hurricane

on the

that climatology can be

removed completely from the forecasting program.

1. The table compares the behavior of the current models to the proposer's future models. The mance of the current models is also likely to improve over the next two to four years.

perfor-

II Proposals > Research Proposals: Objectives and Hypotheses

193

Research Proposals: Design and Methods

The "Design and Methods" you plan

to

section of a research proposal

or two), so you must summarize instead of elaborate. is

summarizes the experiments

perform. Again, most proposal templates don't permit you

much

that

space (a page

A typical organization for this section

as follows:

•

Overview. Provide a good introductory paragraph about your experiment.

•

Methods and need.

Where

posing

a

Materials. Explain your technique

and the experimental

appropriate, identify any techniques pioneered by others.

are pro-

multipart experiment, summarize each of the major parts.

Data Analysis (or Evaluating Results). Describe the

•

tools you'll

If you

apply to the data. Explain

statistical tests

why your chosen method of analysis

is

your team

will

appropriate.

For example, consider the following experimental "Design and Methods" section:

Design and Methods (sample)

Our algorithm breaks down the interaction of

of

hurricane and environment into a series

15-minute "steps." After each step, our program examines deltas

hurricane's three-dimensional shape and

in

in

both the

the surrounding environment. The

algorithm models this pas de deux, readjusting the dance floor after each move.

team will evaluate environmental data provided by the (NHC) from 1992 to present. (Data sets prior to 1992 do not contain enough detail for our purposes.) These data sets are very large and 15 require a tremendous number of floating-point calculations (~10 ) to compute a

Methods and Materials. Our

National Hurricane Center

single 120-hour forecast. To handle this load,

machines sharing 8

We

GB

of

we

require high-speed, eight-CPU

RAM.

plan to write approximately 1.2 million lines of

C code and

approximately 3.5 million lines of existing public-domain Data Analysis.

The

NHC

C

to take

advantage of

code.

currently uses a simple standard metric for determining the

accuracy of predictions. Every

six hours, they

actual and predicted positions of the storm.

measure the distance between the of these measurements yields

The mean

the accuracy of the forecast program. To ensure meaningful comparisons, this

we

will

use

standard accuracy metric as well.

As Zeven (2001) notes, seasons in which storms move slowly yield greater projective accuracy, even without any actual improvement in diagnostic programs. Therefore, we will also supply a second metric that factors in the speed of each storm.

I

194

Proposals > Research Proposals: Design and Methods

Book Proposals Writing

book

a

is

one of the

The Opening Moves

A

in

best things that

to

improve your

career.

Book

Writing a

dressed publisher

nattily

you can do

at a

conference caught your presentation and asked

if

you'd consider expanding the topic into a commercial book. You were hoping he

would

you launched

ask, so

always dreamed

second pitch

of writing.

into a sparkling

He

liked

it,

so

60-second pitch on the book you've

now

is

your chance to develop that 60-

book proposal.

into a

Understanding the Audience Publishers are erudite, highly intelligent, well-spoken, friendly people

only interested

in

Selling lots of

one

who

are typically

thing:

books

know every mover and shaker in your field and will drop names to prove it. know every book published in your field. They know which of these books

Publishers

Publishers also

and which did

sold well

Some

not.

background

technical publishers have a strong

in

your

field.

may even have worked

or graduate school, and a few

in college

and are up

Some

studied the field

to date with current trends

and

buzzwords. However, full-time publishers are not current practitioners of your

field

lishers typically attend a lot conferences

won't

know

nearly as

Most people

many

specifics as

believe that authors

come

pub-

in the field. Technical

and

you do. Publishers run wide but not deep. to publishers with ideas. Indeed, that does

occasionally, but usually publishers think

up

titles

and then go

in search

happen

of authors.

If a

publisher approaches you for a book, then chances are decent that he's already figured out that the

book

will sell.

Strategy Publishers' pay

books

will

turnover

is

lisher that

is

tied to

how many books

soon be searching for another

they

sell.

Those publishers

astounding.) Therefore, the overall strategy

you can write

a

book

that sell only a few

job. (Publishing jobs are highly competitive, is

and

"simply" to convince the pub-

that will sell lots of copies.

To do

so,

your book proposal

should convey the following:

Proposals > Book Proposals

195

•

You can write book.

well.

If you can't

The

make

best

way

to prove this

is

your cause. The ultimate proof of your writing well- reasoned is

•

book proposal

skill is

magazine

a successful

will help

boost

submitting a beautifully

clear,

that follows the publisher's template. (Yes, the pressure

on.)

You understand the market. Your proposal must explain who and why your book

•

have already written

to

that claim, a well-written article in a

will beat

them.

Remember

You can meet the schedule. Publishers ers

who

— publishing

love writers

who

the competitors are

is all

about money.

hit all their deadlines.

Writ-

miss deadlines cost the publisher money.

What Does Not Impress Commercial Publishers? The following •

will

not improve your chances with publishers:

Fame. Unlike

fiction,

consumers

rarely

buy commercial technical books based

on the author's good name. (On the other hand,

if

you are producing a book for

an academic audience, intellectual fame helps considerably.) •

Lab reports. Publishing many reports

in

research journals proves that you are

an important researcher but doesn't prove that you can write a good book.

Contents of a Book Proposal

Most publishers provide extensive book proposal templates, which include

a subset

of the

following items:

•

abstract

•

biography

•

list

•

marketing

•

detailed outline

•

schedule

of previous publications

The following page contains

the marketing section of a proposal for a

new programming language named

Ill 196

Proposals > Book Proposals

Fenster.

book on

a fictitious

Book Proposal: Example Marketing Section Who I

will

are the primary and secondary audiences for your book?

aim

this

book primarily

in Fenster before.

Members of to

buy

audience

this

at least

professional

at

programmers who have never programmed

Such programmers typically already own many programming books.

may

already

own one

of the competitive

two commercial manuals when attacking

The secondary audience

a

but they prefer

titles,

new programming

consists of students. Currently, Fenster

is

language.

very popular with

com-

puter science and traditional science students. However, because of financial constraints, this

audience rarely buys commercial books unless

Fortunately, several universities have just

What

How

are the competitive books?

begun

will

a professor requires the

books

for class.

to offer Fenster courses.

your book compare to them? What

is

unique about your book?

The competitors

are as follows:

The Joy of Fenster (by Arnold Ziff

•

because

it

)

is

the

were annoyed by the lack of examples twice as

many examples

Fenster Goes to

•

title.

most popular book on

was the only book on the topic

in this

book.

features a lot of

My book will

contain

humor

is

is

Amazon

more than

the second most popular Fenster

(as will mine),

which seems

to appeal to

community. The book's coverage of window manipulation

ture of Fenster)

primarily

this topic,

Reviewers on

as this one.

Monte Carlo (by Leonard Hacker)

The book

the Fenster

for almost a year.

my book

very weak;

will

(a crucial fea-

window

provide extensive coverage of

manipulation.

What

is

the appropriate price for your book?

Both of the competitors to

compete

partially

on

sell

for a

list

price of $34.95.

What are the proper venues conferences, and so on) to

Both of the competitors are

(e.g.,

sell

a

propose to

list

the

book

for $29.95

commercial bookstores, academic bookstores,

your book?

selling briskly

through online and traditional bookstores, so

these should be the primary venues. Since Fenster

aim

I

price.

secondary marketing effort

at

is

catching on at universities,

academic bookstores, particularly those

we should com-

selling to

puter science departments.

The annual

Group (FUG) conference would be a natural place to sell this made a presentation at FUG last year, and his publisher was present

Fenster User

book. Leonard Hacker to take orders.

Proposals > Book Proposal: Example Marketing Section

197

Business Plans

Business plans aim to get

money to

start a

new

business or to expand an existing business.

Understanding the Audience

The

target audience for business plans includes potential investors, often venture capital-

ists.

Members of this audience

healthy return

Some venture

on

read business plans to determine whether they can

capitalists started off as technologists

a

and gravitated towards business. Other

venture capitalists have no formal training in technology but are conversant with business plan should assume a technologically sophisticated audience ably comfortable with jargon but has very

Venture capitalists typically

little

interest in

—one

deep technical

that

it.

is

Your

reason-

detail.

know your market extremely well. They will know which com-

panies have succeeded and which have failed. They will have deep-seated theories

works and what

make

their investment.

on what

doesn't.

Strategy

Many

technologists mistakenly believe that business plans should focus

on technology.

True, a business plan must explain the business's underlying technology; however,

focus

on how

the

company

A business proposal

is

will

make money and reward form

essentially a request to

a stranger.

Under what circumstances would you

lowing

might be helpful:

•

list

The stranger has business experience.

its

it

must

investors.

a financial partnership, oftentimes with invest

money

with a stranger? The

fol-

Investors are understandably skeptical of busi-

ness novices. •

The stranger's business is already successful. Note to

•

expand often write business

The stranger want

explicitly states

how

that

want

good business plan explains how the

investors

out of their investment.

•

The

•

The stranger has

stranger's ideas are clear identified a

and

sensible.

The proposal

market and a plan for

posal details the size of the market

and

doesn't hide anything.

selling to this market.

a plan to beat the competitors.

the proposal handles contingencies for a shifting marketplace.

Ill',:

198

companies

investors will recoup their investment. Investors

to cash out after a few years, so a

will transition

that existing

plans.

Proposals > Business Plans

The pro-

Furthermore,

•

The stranger is no longer a stranger. Again, would you really want to invest money with someone you didn't know? Probably not. Once you identify a group that invests in

your kind of technology, try to find

cipals.

Maybe

of

a friend

a friend

a

connection with one of the investment prin-

could help you.

Contents of a Business Plan Business plans are

less

"templated" than other kinds of proposals, so you have

amount of organizational freedom.

Nevertheless, a

good business plan contains

a fair at least the

sections listed in Table 13-1.

TABLE

13-1

Sections

in

Section

a Typical Business Plan

Details

Front matter

Provide a cover

(see "Proposal Element: Cover Letters" on page

letter

184), cover page, table of contents,

Executive

Summary

summary

Provide a quick

and so

on.

or abstract for busy readers. (See "Proposal

Element: Abstracts" on page 187.)

Company

Provide a brief corporate history. Detail

how

the

company

funded and who owns the company. Provide bios

for

is

currently

your company's

management team. (See "Proposal Element: Biographies" on page 185

for help

on

bios.)

Explain the technological basis for the company. define what you are trying to

Support

Explain

who

will

provide customer support.

Market

Explain

who

will

buy

this

In

other words,

sell.

good

or service.

If

you are breaking

into

an

and future market. If this is a new market, provide realistic estimates, preferably based on reputable market research. What market share percentage can your existing market, describe the size of the current

company achieve? Be Marketing

realistic.

Describe your marketing plan. Explain how the proposed company will fulfill

the market better than

competition.

its

How

big will your

sales force be?

Manufacturing and Distribution

(If

you are selling a service rather than a product, skip this section.)

How

will

you manufacture your product?

ers buy your product?

Finances

In

you do with the investment?

Detail

what venues

a distributor

Detail both your current financial position will

Schedule

Do you have

How

what your proposed company

will

will

in

will

custom-

place already?

and your projections. What investors cash out?

achieve and by when.

lilli Proposals > Business Plans

199

Summary

of Proposals

Before submitting your proposal

dry cleaning

really

— while

lying

would have been more

awake

satisfying

AM, wondering

3:00

at

— turn on the

light

if

a career in

and ask yourself

the following questions about your proposal:

•

Has someone edited the proposal want

to

submit

a

for spelling

and grammatical errors? (Do you

proposal that contains typos?)

really

the writing clear? Are the sen-

Is

tences a struggle to read? Are the fonts obtrusive? •

Has someone outside your team reviewed the proposal? The one with similar credentials proposal

•

make

sense to the reviewer?

Can

•

some-

abstract? E-mail only the abstract of

your proposal to several colleagues and ask them your colleagues don't get

is

members. Does the

the reviewer find any logical fallacies?

Has someone outside your team reviewed the really about. If

ideal reviewer

to the proposal review committee's

it

to describe

what the proposal

is

right, consider rewriting the abstract.

Have you followed the proposal template very

Have you looked

closely?

at successful

proposals and mimicked their style? •

Does your cover committee

•

to

letter

contain your current contact information? You don't want the

send the check to the wrong address.

Does your bio do you

justice? Will proposal reviewers

be impressed by the person

described in the bio? Will your experience impress the target audience?

you •

If

with someone

allied yourself

you

who

are writing a business plan or a

across, or

do you sound

like a

will

book

If

not, have

impress proposal reviewers? proposal, does your business focus

come

pure techie? Does your proposal provide a cogent

description of the current market? •

Do

your budget

for only $50?) •

line items

Do

sound

realistic?

(Can you

really

buy two new computers

your budget columns add up?

Do you come across as a grounded, well-organized

individual, or

do you sound com-

pletely scattershot? •

Does your proposal handle contingencies other than the best-case scenario?

200

Proposals >

Summary

of

Proposals

effectively?

Have you explained anything

CHAPTER

14

Internal Planning

Documents

The

previous chapter looked

documents aimed

at

organization. In this chapter,

we

at

readers outside your immediate

turn our gaze inward to study documents that you

write for people within your organization. Instead of the wolf outside your door,

you are now trying to please the jackals

in the next cube.

This chapter focuses on the following three kinds of internal planning documents: •

Business proposals. These

management of your •

recommend new products

High-level technical specs. These summarize a that even the vice president of

•

new products

The key

to

and what

all

it

how your own

engineering team will

understanding

who your

or technologies.

three types of planning

documents

is

audience

is

cube over, needs very different information than Sam Minyon, the well-

shod gentleman who heads procurement

Will

or technology so simply

needs to get out of each type of document. Dr. Chekirnov, the barefoot biol-

ogist in the next

They

new product

marketing can understand them.

Low-level technical specs. These detail exactly build

or technologies to the upper

organization.

Know You by Your

Internal planning

in the

corner

office.

Writing

documents, particularly business proposals and high-level technical

specs, are very important to your career. Writing a clear, well-considered proposal or

spec

will

speak volumes about your organizational

abilities.

Conversely, cloudy specs

suggest cloudy thinking.

Internal Planning

Documents

201

Business Proposals

Business plans to

new company

sell a

an existing company.

pany ought

is

you

to be doing, then

idea to upper

company

If

are

to potential investors. Business proposals sell a

an engineer with

you would

management. Writing

a great idea for

new

typically write a business proposal to sell

a business

idea

something your comyour

proposal that changes the direction of your

invaluable to your career, particularly

if

the project

is

a success.

Understanding Your Audience

Aim your

business proposal at the upper

management

management

includes not only engineering

pletely nontechnical areas. Further note that the top

nization

is

typically years

you take

your company. Note that upper also

management

management in

in

com-

an engineering orga-

removed from hands-on use of technology and

members of upper management no issues that

in

management but

that

many

longer understand a lot of the nitty-gritty technical

for granted.

What Motivates High-Level Managers? Upper management aims

to

enhance income and reduce expenses by making sound

business decisions. That's the standard answer, anyway. The real-world answer

more complex.

For example,

some

top-level

managers see

to be zealously protected, particularly against

all

forms

of

is

far

their purview as a fiefdom

change. For this reason,

even the most wonderful business proposals sometimes get rejected without due consideration.

The clever

knows

writer

that a great business proposal can only advance as far as his

campaign for a business proposal by managers and encouraging feedback. Once upper-

or her political leverage allows. You should

walking level

it

around

managers

chance

The Keys

to upper-level

feel that

they have a hand

in

the plan, the plan has a far greater

of success.

to Successful Business Proposals

Effective business proposals persuade readers of the following points:

•

The

•

The

project

•

The

idea will not hurt current sources of revenue;

idea

is

a

sound business decision;

is

achievable;

it is

it

will generate a profit or

Internal Planning

costs.

not the fantasy of an idealistic dreamer.

Ill 202

reduce

Documents > Business Proposals

it

may even enhance

current

sales.

To persuade upper management of the preceding points, use the following

tactics:

Rely on market research. Does the market you are proposing already exist?

•

much

revenue does

How much

market currently generate?

this

will this

How

market grow

over the next few years?

Compare your

•

This

to sell

management only

an exclamation point than

Explain

•

how your

company

to

a

believe that

or peer companies.

accepts proven ideas, but

easier

it is

question mark.

idea will outsell your competitors' products. Note that the

market

your idea

first

not always the most successful in that market.

is

Find a corporate champion for the project.

•

own

idea to successful similar projects at your

not to say that upper

is

is

If influential

sound, your idea has

people in the

a far greater

company

chance of success.

Analysis of the Sample Business Proposal

A

two-page sample business proposal begins on the next page.

end

exercise machine.

Note the following points about

this

It

describes a new, high-

business proposal:

•

This business proposal focuses on business principles, not technical

•

This business proposal invokes the names of two corporate champions (Elena and

Bob) primarily

to

announce

ment have already approved

to other readers that

details.

two members of upper manage-

the idea. (Before using this tactic,

make

sure that other

top managers don't hate Elena and Bob.) •

This business proposal contains very few adjectives and adverbs; instead, facts

and

invites readers to

that competitors are •

come

own

bly

still

it

offers

conclusions about the barrels of money

making.

This business proposal uses simple, numerically based graphics to

about competitors. Even people

•

to their

who

don't read every

make

word of proposals

its

points

proba-

will

glance at the two graphics and get something from them.

The graphics omit

the sorry state of the engineer's

company's own revenues have held

flat is

own company:

the fact that the

buried underneath one of the graphics.

(The wise writer doesn't offend the vice president of sales when trying

to

push

a

new

(

VR)

idea that will require her approval.) •

The purpose of the "Background" but to suggest that

word

old.)

The

VR

is

a firmly

section

is

not really to explain virtual reality

entrenched technology. (Notice the use of the

writer did not want readers to think that

VR was

a

new and

risky

technology. •

Figure 14-2 inoculates against the cannibalization-of-market question by

demon-

strating that overall revenue will probably increase.

Internal Planning

Documents > Business Proposals

203

Business Proposal: Example

Our team recommends

that

we

design, manufacture, and market a

stair-stepper model. This business proposal

new virtual

reality

(

VR)

summarizes our recommendations.

Synopsis

Our

R&D team

recommends designing a new stair-stepper machine with VR

machine, which we are dubbing King Kong, features goggles will stair-step.

feel as if

features. This

Customers wearing these

they are climbing up the outside of the Empire State Building as they

The new machine

on additional

VR goggles.

digital

uses the

components

same

to enable

chassis as

VR

our existing 3500 model but

layers

features.

Background Virtual reality

is

term several decades old that means portraying fantasy

a

in as realistic a

VR system would generate perceptions indistinguishable from reality. Commercially successful VR entertainment is now available at movie theatres, fashion as possible.

theme

parks,

The ultimate

and game arcades. Due

now commercially practical rience.

We

can use

VR

The Current Market

Two of our

in

competitors

sold exercise

•

to

to

wed

VR

to gradual drops in digital

produce exercise equipment that

component

offers a

prices,

powerful

it

is

VR expe-

exercise to entertainment.

Exercise Equipment

—Calispindex and Pravda

equipment with some

VR

features.

Mills

— have already manufactured and

These competitive models are

Calispindex SpinCycle VR20. This stationary bike has

as follows:

a small flat-panel screen that

projects images of a rolling rural countryside while the customer exercises. As the terrain changes, the bike reacts accordingly. For example,

uphill portion of the course, the bike •

becomes harder

Pravda Mills Tread- 1000. This treadmill has similar

when

the screen shows an

to pedal.

digital

components

to the Spin-

Cycle VR. While running on the treadmill, customers view actual images from the

Boston Marathon course.

Both companies featured these two

VR

products in their

last

two annual

reports.

The

pie

charts in Figure 14-1, taken from data in their annual reports, illustrate the growing impor-

tance of

VR

equipment

to these

two companies.

II 204

Internal Planning

Documents > Business Proposal: Example

Year 2004

Year 2003

\B

Calispindex

V

29%J

Sales revenue of

equipment with virtual reality features

Sales revenue of

/78%

^

\^

/\

Pravda Mills

V

22%/

°\

VR-based equipment accounts

FIGURE 14-1

Did the growth machines? In

in

VR equipment

fact, as

nificant overall

equipment without

490/

for

virtual reality features

an increasing percentage

merely cannibalize the existing market

of sales.

in older,

non-VR

Figure 14-2 shows, both Pravda Mills and Calispindex enjoyed sig-

growth

in

new product

revenue.

$40 Annual Product

Revenue

in Millions

$20

of Dollars

$10

2004

2003

Calispindex

companies with VR equipment have grown.

FIGURE 14-2

Overall sales at

During

same period, our own annual product revenue was

this

2004

2003

Pravda Mills

flat.

Our Recommendation

When

designing King Kong,

we worked

She emphasized the need to enter

manufacturing

we can

sell

the

for this

machine

machine

first

closely with Elena, vice president of marketing.

market as soon as possible. The components and

will cost us

for $2,500

imately 2,000 units in the

this

more per

$750 more per unit than the 3500; however,

we can

unit. Elena estimates that

sell

approx-

year and 6,000 units in the second year.

We estimate approximately nine months from vice president of manufacturing, feels that

project inception to

we can

build this

first

model

in

customer

ship. Bob,

our existing Beloit

factory.

Internal Planning

Documents > Business Proposal: Example

205

High-Level Technical Specs

Once

upper-level

management

gives the

go-ahead to the business plan, the lead engineer

or product manager writes a high-level technical spec, also called a functional spec in

some

industries.

Purpose The primary purpose of a pany prepared

high-level technical spec

for the introduction of a

is

new product

to get

all

helps unite disparate organizations; a really bad spec offends

and ensures

agers

a

bumpy

the organizations in a

or technology.

A

really

com-

good spec

some of the department man-

ride.

Understanding Your Audience This

is

the spec that launches a dozen specs.

Managers read

this spec in

order to write specs

of their own. Therefore, your audience skims over the spec, selectively attending to specific parts that will help

spec

is

them write

their

own

spec.

The purpose of your

high-level technical

not to write the other specs but to provide enough information so that other

agers can

do

their job. For

man-

example, your spec should contain information such as the

fol-

lowing to enable a manufacturing manager to write the manufacturing plan: •

the parts required to build the

•

a

new product

diagram or description suggesting how the parts

Remember

that

many

your audience includes

fit

people with

together

little

neering background. The vice president of sales understands

or no scientific or engi-

how

to sell products, not

how

their innards work.

QUANTUM LEAP Effective high-level technical

mation

for other

specs must walk a thin

line.

department heads without sounding as

The spec must provide if

you've

made

infor-

decisions that

they are responsible for making. Your spec should specify which decisions you are

expecting others to make.

Sections

The

in

a High-Level Technical Spec

sections in a high-level technical spec

in the

The following ing a

206

depend on the

industry.

The

sections for specs

pharmaceutical industry will be quite different from those for the software industry. section

list,

for example,

would be appropriate

good old-fashioned tangible good:

Internal Planning

Documents > High-Level Technical Specs

for an industry manufactur-

•

Synopsis

•

Components

•

Assembly

•

Schedule

•

List

of Issues

The synopsis

is

most important part of the entire functional

the

spec.

Given the harried

schedules of most executives and their general disinclination to read specs,

only read the synopsis. For this reason,

will

and (dare

The

I

say

it)

vital to create a concise,

it is

exciting synopsis.

technical overview should explain what other departments need to

product. Remember, you

own

still

the

list

know about

the

have the low-level technical spec to detail everything your

engineering group needs to

The schedule and

many executives well-organized,

know about

the product.

of issues often serve as the basis for regular cross-functional team

meetings. In the opening draft of the high-level technical spec, you typically don't want to give too

many

schedule details, particularly those for other departments. (Managers from

other departments won't want you to get too involved with their schedules.) Nevertheless,

you

still

whining

need to put out some broad starting dates. Then,

just sit

back and wait for the

to begin.

Analysis of the Sample High-Level Technical Spec

The sample

high-level technical spec that begins

on the following page straddles the skinny

between providing enough information and not making decisions

line

ments. The following •

is

a list

The spec does not include information on information had to be

•

in the

making

as they please in

The spec includes

•

The "Assembly"

a fairly detailed list

list

out,

sales will

do

of components, which will be useful for the

carefully distinguishes

and components with open-ended

between components with

suppliers.

section contains a few critical details but provides openings that the

specs, details such as

worked

now marketing and

the decisions.

relevant people in other departments

•

pricing or marketing. True, this sort of

business proposal, but

procurement department. This specific suppliers

for other depart-

of key points from that spec:

how

must complete.

the laptop will be

In

some

mounted would

high-level technical

already have been

and the spec would contain complete diagrams.

The schedule

is

fairly sparse.

A

project

manager or

erate a full schedule containing perhaps several

project leader will ultimately gen-

hundred milestones

for a project of

this complexity.

Internal Planning

Documents > High-Level Technical Specs

207

High-Level Technical Spec: Example

All a

department heads

new product be the

will

exercise

first

will

many

of

Climber

at Social

we

that

should read

Inc.

develop during the year.

virtual reality

(VR)

If all

exercise

this functional spec.

goes as expected, this

machines that blur the

It

highlights

new product line

between

and video games.

Synopsis This spec details the proposed King

machine with

a digital twist.

the great ape climbs

up the outside of the Empire

at

is

high-end stair-stepper

a

the climax of the movie King Kong,

State Building.

The 4500

without fighter planes shooting

ers enjoy a similar experience (but a

Kong Climber 4500, which

As movie fans know,

at

will let

custom-

them) while getting

workout.

The key

to the

4500

computer monitor

is

a pair of

VR

goggles. These goggles are essentially a very, very tiny

that displays images.

As

a

customer climbs steps on the 4500, the gog-

images from the Empire State Building. For example, when the customer has

gles display

climbed the equivalent of 100

feet,

the goggles will display the view from 10 stories

up

at

the real Empire State Building.

Technology Overview All the

mechanical aspects of the King Kong Climber 4500 are identical to those of the cur-

Climber 3500. In other words, both

rent Social

However, the 4500 has significantly more

DVD

The

4500

that the

is

the

recently proposed a 5500

make

on the same

chassis,

first

legal

department

of many proposed

is

come from

in negotiations

VR exercise systems.

model based on multiplayer

sure that parts suppliers understand that

motor, and pedals.

components than the 3500.

of images from the Empire State Building will probably

named Acrophobics' Nightmare. Our Note

rely

digital

we

virtual races

are in this

a

company

with them.

For example,

up

tall

we have

buildings. Please

market for the long run.

Components In addition to the

•

A

Zebra-5

components

kit,

in the 3500, the

Dexco

is

also requires the following:

manufactured by Dexco Unlimited. This

ware we need preassembled.

•

4500

It is

Goggleplex's preferred

essentially a laptop

kit

without

has a

all

OEM.

Goggleplex Omega 20, manufactured by Goggleplex Inc. These are the virtual goggles that the Zebra-5 is

no

alternative

kit requires.

There are no standards

for

VR goggles,

vendor for the goggles.

Hi 208

the digital hard-

keyboard or monitor.

Internal Planning

Documents > High-Level Technical Spec: Example

reality

so there

CD

•

A

•

A 15-amp power supply from any 12

supplier.

is

creating the software.

Note that the 3500 model draws only

amps.

Assembly The Zebra-5 provides at

R&D

containing the software to run the 4500.

its

own

We would

chassis.

manufacturing

like

mounting mechanism

the top of the Y-bar, using a

to

to

mount

this chassis

be determined by the mechanical

engineering and manufacturing departments. Note the following additional assembly requirements: •

A CD must accompany

•

A hard-copy documentation

each

kit.

set

must accompany each

kit.

Schedule Table

TABLE

1

1

contains a proposed high-level schedule for the 4500.

Schedule

for Initial

Development and Deployment

of the

4500

Department

Milestone

Date

All

Detailed plans due

Jan. 7

R&D

Prototype

Mar. 5

R&D

Software development functional freeze

Mar.

Beta test

Apr. 27-Jul.

QA

Marketing and

R&D

Final software

development freeze

Internal testing

Documentation

Final

Manufacturing

Production of

Manufacturing

Production of 250th unit for customer sh ipment

final

model

Aug. 31-Sept. 30

manuals printed 1st unit for

27

Aug. 24

QA

on

26

29

Sept.

customer shipment

Oct. 6

Dec. 8

Preliminary Issues

The following

issues

must be tracked

•

How do we document

•

Do we need

at regular

team meetings:

safety issues for climbing stairs while

to license the

name "King Kong"

Internal Planning

wearing

VR

goggles?

for this product?

Documents > High-Level Technical Spec: Example

209

Low-Level Technical Specs

Low-level technical specs, called design specs in

aimed

at the

engineers in a group

some

industries, are detailed blueprints

who must implement some

new product

aspect of the

or technology. The lead engineer or engineering manager writes such specs.

Purpose Low-level technical specs explain the work to be done,

who

will

do

it,

and when

it

must

be finished.

Understanding Your Audience Your audience consists of all the engineers

in

your group. Therefore, use plenty of jargon.

C programming

For example, the spec should not waste time explaining the engineers

A

who

already

program

typical project consists of a set of subprojects, each

You

no obligation

are under

projects. For

to provide the

same

implemented by

must

more

latitude. Nevertheless, to

clearly define the interfaces

ensure a smooth project,

between the different subprojects. For example,

the spec should define the data to be passed between two different

Sections

in

different engineers.

of detail for each of these sub-

level

example, the spec should typically provide plenty of details for junior engi-

neers but allow senior engineers the spec

language to

in C.

programming modules.

a Low-Level Technical Spec

All low- level technical spec

should contain a synopsis of the project and a detailed schedule.

Beyond those two requirements, each low-level technical spec depends on the industry and the project.

Analysis of the Sample Low-Level Technical Spec

A

sample low-level technical spec

from •

this

starts

The "Synopsis"

The

different

detail for

"Team"

is

that success will lead to

a lot

is

on the prime

an inexperienced engineer, so the "Team

highly experienced, highly independent engineers is

who

quite

flourish in a creative environ-

open-ended and only

few requirements.

Ill Internal Planning

relies

interesting projects.

of low-level details for him. Marietta and Eswar are

ment; therefore, the "Team C" part of the spec

210

It

more

sections are personalized to provide the appropriate level of

each team. For example, Randy

A" part of the spec provides

a

the following key points

section aims to motivate the target audience.

engineering motivator, which •

on the next page. Note

sample:

Documents > Low-Level Technical Specs

lays

out

Low-Level Technical Spec: Example

The software engineering team (Randy, which

spec,

details

how we

Jenny, Eswar, Jim,

and Marietta) should read

this

implement the 4500.

will

Synopsis

As you already know, the 4500 adds

VR, the 4500 adds to a pair of

VR goggles.

As

Our team must develop This

is

our

first

of these, the

of using

PROMs All

board and monitor), which laptop's

TABLE

if

To implement

their virtual height.

we

get

it

right,

it

is

and

much more complex a tiny bit

of

RAM,

hardware components will

won't be our

last. If

we can

than anything we've done

we're

now working

with

inside a standard laptop

fit

sell

enough

year.

all

in the

the hard-

(minus key-

be mounted at the top of the Y-bar. Table 14-1

lists

the

components.

14-1

Laptop Components

Component

Spec

CPU

Motonel 5 Series

RAM

256

DVD

features to the 3500.

do even cooler products next

will let us

ware power of a laptop.

VR)

the software to enable this marvelous act of digital deception.

Hardware The hardware implementation past. Instead

(

customer climbs, the images change with

a

all

VR product, but

company

virtual reality

(minus keyboard and screen) that wirelessly transmits images

a laptop

player

Networking

MB SIMMS

at 3.2

GHz

running at 400

MHz

A 12X read-only player Ethernet board + Goggleplex wireless card (signal

We'll be fighting over

is

robust for -2.5 m)

who gets to use the Goggleplex Omega 20 virtual reality goggles. The Omega 20 goggles is 1024 x 800, but because the images are less

actual resolution of the

than an inch away from the customer's eyes, the effective resolution

We've already taken delivery of two units that our team can use

for

is

ludicrously good.

development and QA.

Software Requirements

Our group

will

develop the software for the 4500. However, we

Building images from another firm. Note that

Internal Planning

we will

rely

will

buy the Empire

State

on our usual source-code control

Documents > Low-Level Technical Spec: Example

211

system and build Since

all

OEM who assembles our laptop will preinstall

The

utilities.

Goggleplex APIs are

in C,

we

will write all

code for

Red Hat

4.3.

this project in C.

divided the software project into three teams.

I've

Team A (Randy) Team A must create statistics

from

API

a small

The

it.

statistics

to fetch the exerciser's

number of steps. Write

and

total

and

listen for

workload every

0.5 sec

must include cumulative height climbed,

and generate

calories burned,

the statistics into a 6000-element array.

Open

a socket,

two possible requests:

•

Request "1" means send the most recently updated row

•

Request "2" means send the entire (nontrivial) part of the array.

in the array.

Team B (Jenny and Jim) Team gles.

the

must

13

on the

rely

existing Goggleplex display

API

to transmit

To gather the most recent height reached, use sockets

most recent height

on the

DVD

above the

to the appropriate

show views

street,

image

m

0.5

1 1

apart. For example,

Team C (Marietta and Eswar) Team C will develop the GUI. Note

images to the

send Request

"1."

VR gog-

Then,

map

image on the DVD. Note that successive images

the view from 5.5

is

to

image 10 shows the view from 5.0

m

m, and so on.

that the goggles are not only an

output device but also

an input device that can detect pupil motion (equivalent to mouse motion) and eye blinks (equivalent to

mouse

clicks).

The GUI should provide

a quick

shutdown

to allow a panicked

customer

to exit

immediately.

At the end of the session, the

GUI

should display

a

graph (based on data

in the array)

show-

ing height versus time, which identifies the fastest and slowest parts of the session. To get the data, use sockets to send Request "2."

Detailed Schedule

[Omitted for space reasons.]

**

212

Internal Planning

Documents > Low-Level Technical Spec: Example

Summary When •

reviewing a business proposal you have created, ask yourself the following questions:

Did you

Is

Is

possibly, the

that

your business proposal persuasive?

•

the right thing for the

is

It

supposed

really shouldn't

most of the people reading It

keting information, leading readers to this project

is

to be high-level

board of directors or various investors

your business proposal too technical?

Remember •

audience? The target audience

hit the target

managers and, •

Documents

of Internal Planning

it

do not have

in the

company.

be very technical a technical

at

all.

background.

should rely on cold, hard, numerical mar-

come

to

one inescapable conclusion: doing

company.

Have you "presold" the business proposal by talking

it

over with various upper-level

managers? Does the business proposal invoke the names of several important proponents?

When

reviewing a high-level technical spec you have created, ask yourself the following

questions:

•

Did you (often

own •

audience? The target audience

hit the target

managers but possibly project leaders) who

supposed

to be the people

departments.

Did you make the spec too technical? The head of procurement does not care what language you are coding

•

is

will write detailed specs for their

in.

Did you provide enough information

for the

head of procurement or head of man-

ufacturing to write their specs? •

Did you provide too much information about marketing? You shouldn't provide

much

When

detail at

all

about marketing or

sales.

reviewing a low-level technical spec you have created, ask yourself the following

questions:

•

Did you

hit the target

audience? The target audience consists of all the people in your

immediate engineering organization. •

•

Did you make the spec technical enough? This group Did you provide enough information After

all,

that

is

really

needs technical

for the engineers to get started

on

details.

the project?

the goal for this sort of spec.

Ill, Internal Planning

Documents > Summary

of Internal

Planning Documents

213

CHAPTER

15

Lab Reports

Although most scientists love doing research, many hate writing lab reports. This a real pity

because a

muddy lab

is

report can soil even the best experiments. Imagine

researching a topic for years, getting valuable results, and then being refused for publication just because editors and reviewers did not understand what you are trying to say. Surely,

though, that won't happen to you

— not with your

clear, concise,

accurate writ-

ing style.

Lab reports typically consist of the following sections: •

The

Abstract

•

Introduction

•

Materials

•

Procedure

•

Results

•

Discussion

•

Conclusion

•

References exact

list

of section names varies somewhat between disciplines and journals. For

example, the "Materials" section ment."

Some

is

sometimes

called

"Methods and Materials" or "Equip-

journals require additional topics.

About the Experiment

in

This Chapter

The experiment described

in this

the citations and references

simply an example to

in

illustrate

chapter never happened;

I

made

this chapter are also fictitious.

how

it

up. In addition,

The experiment

is

to write lab reports.

VsS!

Lab Reports

215

Abstract

The

"Abstract" section presents the entire lab report in miniature. Abstracts

running only

short,

impose

a single paragraph. Journals

different length

must be quite

and

style require-

ments, to which you must pay careful attention. Abstracts must be strong

enough

on

to stand

their

own. Your abstract

will

probably be

placed in a collection of abstracts. Readers browse these collections to determine which lab reports are worth reading.

amount of energy on

If

you are trying

to attract readers,

more

the abstract. Note that far

you should expend

a fair

readers will read your abstract than

of your lab report.

will read the rest

"""quantum leap I

recommend

writing

them

last,

it

you can

lift

list

By

key sentences from other parts of the lab report and use

(or slightly modified versions of

The following 1.

writing the abstract after you have written the rest of the lab report.

them)

in

your abstract.

presents a possible template for creating an abstract:

Begin with a sentence or two that summarizes the hypothesis that your experiment addresses.

You may optionally phrase summarize

this

opening

as a rhetorical question.

on the hypothesis.

2.

In a sentence or two,

3.

In

two or three sentences, describe the experiment.

4.

In

one

5.

Conclude with

to three sentences, a

relevant research

summarize the

sentence explaining

results.

why

the results are important.

Abstract

Does a

child's focus correlate with barometric pressure?

If

so,

does

it

correlate

positively or negatively? Tucker (1999) hypothesized a negative correlation, but this

assertion has never been tested. Our

team used the MISHA CPT

focus of a group of 150 third-grade students.

We

to

measure the

divided the students into three

50 students. One group took the MISHA CPT when barometric pressure it when barometric pressure was neutral, and the final group took it when barometric pressure was high. The results found that children focused significantly better when barometric pressure was low than when barometric pressure was neutral or high. The results suggest that when diagnosing ADHD, groups

was

of

low,

another group took

practitioners should give the

t, 216

Lab Reports > Abstract

CPT when

barometric pressure

is

neutral.

Introduction

Begin the "Introduction" section by identifying the purpose of the experiment. In other words, identify the question you are trying to answer. Try to identify the purpose in a para-

graph or two, although for "wide" studies, you

may need

to provide multiple paragraphs

or even multiple pages. After stating the purpose, explain the theory (or theories)

experiment. In your explanation,

cite

digress too far into tangential studies.) Identify not only

done but

also

what

on which you have based

the

previous relevant research on this topic. (Don't

what previous researchers have

their research did not cover. Citing research helps bring readers

up

to

speed on the current thinking about this topic. In addition, citing research helps you avoid potential plagiarism charges.

As always, audience definition

knows and then supply the

is

essential

—

must

delta they

figure out

what your

The audi-

many of whom

are fellow

ence for lab reports typically consists of highly educated experts, researchers.

However, highly educated experts are typically highly specialized and might

not be familiar with current research in the broader

The introduction should

also explain

your audience. For example, consider elements.

If

you are targeting the

field.

any special equipment that might be unfamiliar to a lab

report based

on an experiment

lab report at a journal that focuses

uranium elements, your introduction should not waste the usual lab equipment in that that prints

target audience already

learn to understand your experiment.

all

field.

If,

in

transuranium

on research

into trans-

reader's time explaining the

however, you are targeting the lab report

at a

journal

types of physics research, then your introduction should explain the

apparatus.

The following sample introduction

targets a periodical that publishes general psychological

research for a broad range of psychologists.

If

the target periodical were devoted to the

study of Attention Deficit Hyperactivity Disorder

(ADHD), then

the author

would have

omitted most of the background information about the Continuous Performance Test

(CPT). Note that

a real

introduction might be considerably longer than the sample.

I Lab Reports > Introduction

217

Introduction

This experiment seeks to determine whether barometric pressure influences a child's focus. In other words, does a

change

in

barometric pressure change a child's

ability

to focus?

Tucker (1999) hypothesized that changes responsible for the large variances days.

She suspected

in

in

barometric pressure might be

focus that the

a negative correlation

same

child exhibits on different

between barometric pressure and focus,

Siska (2003) determined that focus changes within a child were negatively correlated with blood-sugar levels. However, Siska noted that the correlation

was somewhat

less

than predicted and suggested that other environmental factors (including weather)

might be responsible

changes

same

within the

The

for the delta.

Mackinson and Goldberg (2004) found that

ambient temperature accounted

in

literature

for relatively

sharp changes

in

slight

focus

child.

does not provide any studies that correlate focus with barometric

pressure.

Our experiment attempts focus better on days

to prove Tucker's hypothesis. We, too, suspect that children

when the barometric pressure

is

low than they do on days when

we sent an informal 50 elementary school teachers randomly selected in the Washington Of the 32 responses we received, 28 teachers indicated that students were

the barometric pressure

is

high. Prior to beginning the study,

e-mail survey to D.C. area.

"more manageable" on

rainy

days than on sunny days. (Barometric pressure

is

usually lower on rainy days than on sunny days.)

To measure focus, our team relied on the Continuous Performance Test (OPT). The

OPT

is

currently the

most widely used instrument

for studying

focus and for

diagnosing Attention Deficit Hyperactivity Disorder (ADHD). The

program that looks

to

most children

like

CPT

is

a sort of primitive video game.

a

computer

The CPT

displays a series of letters on a computer monitor. Children respond by typing certain

keys on the computer's keyboard. The version of the lasted approximately 14 minutes. Although

diagnosing ADHD, the

any child's

MISHA CPT

is

most

CPT we used— MISHA CPT— CPT when

clinicians use a

also an accurate

assessment

Unlike temperature and relative humidity, barometric pressure

is

typically the

indoors and outdoors. Therefore, testing children indoors offers as testing

tool for defining

ability to focus.

much

same

validity as

them outdoors.

The MISHA CPT generates 12 separate parameters and a summation index. The summation index is an integer between 1 and 100, with 1 representing an almost infinite attention

span and 100 representing severe ADHD.

1 218

Lab Reports > Introduction

Materials

The "Materials"

section should state exactly what

equipment you used, leaving

nothing to the imagination. For example, the following

If

•

light

•

24

suspicion, like

to get? Probably not. Furthermore, if it

would be embarrassing

the following

•

24 incandescent

•

24 Wistar male

•

a

is

more

60W

they

know what

admit that your lab report omitted key materials.

to

reproducible:

light

rats, all

will

your lab report generates controversy or

bulbs arranged in a 6 x 4 rectangular matrix (see Figure 2)

between 10 and 12 weeks old

Hyperion Rat Habitat, Model 260-R

equipment

If your

and If

bulbs

another lab team wants to reproduce the previous experiment,

list

practically

not precise enough:

rats

equipment

A

list is

falls

several distinct

the test subjects are

explain

into several categories,

it is

usually clearer to create several subheads

lists.

how you chose

humans,

create a

subhead

called "Subjects." In this subsection,

the subjects and any relevant information about their background.

Materials

Our team

relied

on the following hardware and software: each running MISHA CPT v2.1 on Windows XP

•

25 identical

•

A detached "desktop-style"

•

A

digital

Dell laptops,

Dell

keyboard (not the laptop keyboard)

barometer: the Dexco Unlimited model B-16

Subjects

We

tested 150 third-grade students chosen at

random from

a pool of

346 applicants

from eight Washington D.C.-area public and private elementary schools. The students represented a participate

in

our study

fairly in

wide range

exchange

economic backgrounds. All agreed to $50 gift certificate from a local toy store.

of

for a

Lab Reports > Materials

219

Experimental Procedure

The experimental procedure

Do not

idealize,

do not

section should detail the exact experiment that your team ran.

fabricate,

and do not aggrandize

experiment so that another lab team could If

the experiment consisted of a series of steps that

the procedure as a

numbered

list.

—

just

faithfully recreate

tell

the truth. Describe your

your experiment.

happened

in a distinct order, present

Otherwise, present the procedure through standard

-

paragraphs. If your

experimental setup

providing illustrations.

A

is

complex, nonintuitive, or

few good illustrations

clarify

just plain

hard to describe, consider

an experiment and reduce potential

ambiguity.

Experimental Procedure

We of

December school we tested on three

tested our subjects during the

barometric pressure readings,

vacation week. To ensure a range different

days (Monday, Tuesday,

and Thursday).

We

randomly divided the 150 subjects

limitations,

we randomly

B) of 25 subjects each.

We

tested subjects

test.

The

The experimenters

in

After a brief pause, the

CPT

of 50.

Because

of

hardware

at

4:00 and Group B

A and

at 5:00.

Subjects could neither see nor

test consisted of the following steps: test,

experimenters ushered each

a large lab area.

test

computer would provide instructions

would only take about 15 minutes.

computer monitor displayed instructions

for using the

while a recorded voice read the instructions aloud. (The text and audio

instructions are the standard

Appendix A 4.

Group A

told subjects that the

and assured the subjects that the 3.

in

Approximately three minutes prior to the subject into a separate cubicle

2.

groups

4M 2 cubicles.

Subjects took the test inside separate

hear other subjects during the 1.

into three

divided each group of 50 into two subgroups (labeled

MISHA CPT

instructions for children; see

for a transcript.)

At the conclusion of the test, an experimenter ushered each subject back to a

waiting room, where subjects were reunited with parents or guardians.

The experimenters measured the barometric pressure (approximately seven minutes after

it

began).

t 220

Lab Reports > Experimental Procedure

at the

midpoint of each

test

Results

The ing

"Results" section details the quantitative

some combination of formulas,

and honest. (Later sections

tables,

will give

you

while striving for truth and beauty, the

a

outcome of the experiment,

and graphs. Keep

typically blend-

the "Results" section objective

chance to be subjective.) Nevertheless, even

statistics

you choose

to provide

and those you

choose to omit can easily bias your readers' opinions of the experiment. Begin your "Results" section with a brief (one or two sentences) reminder of the overall

purpose of the experiment. Follow that brief reminder with

a brief description

of the types

of data your team collected. The prose within your "Results" section should introduce and

summarize each graph or reader's attention

Figure 2

table.

For example, the following paragraph helps focus the

on an important

shows the absorption

gland remaining. The graph

is

result:

of 1-131 as a function of the

linear

percentage

of thyroid

between 15% and 100%, but shows a strong

discontinuity at around 10%.

If

you have

a lot of results, subdivide the "Results" section into multiple subsections.

Do

not give a subsection a meaningless name, such as the following:

Section

A

Give each subsection

a precise subtitle, as in the following

example:

Absorption of 1-131 by Percentage of Thyroid Remaining

Begin each subsection by identifying (in a short paragraph) what kinds of data

this sub-

section covers.

Due

to space limitations, the following page

shows only

a portion of a "Results" section.

Lab Reports > Results

221

Results

The experiment aimed

to

determine whether a child's focus correlated with

barometric pressure. To that end,

we examined

the following types of data:

•

barometric pressure

•

changes

in

each child's focus over the three tests

•

changes

in

the entire group's focus over the three tests

Barometric Pressure Table

shows the barometric pressure during the

1

pressure was low.

tests.

On Tuesday, barometric pressure was

On Monday, barometric close to normal. On

Thursday, barometric pressure was high. The barometric pressure varied very

little

between Group A and Group B within each day.

TABLE

Pressure on Test Days

E iarometric

1:

Group

Monday

A

1002

1015

1025

B

1002

1015

1025

(in

Tuesday

Mbs.)

(in

Mbs.)

Thursday

(in

Mbs.)

Changes Figure

1

in Focus shows three graphs representing the

index on the three testing days. (A lower

[Figure

1

FIGURE

distribution of

summary

MISHA CPT summary

index represents greater focus.)

omitted for space reasons] 1:

Distribution of

The subjects showed

summary

index by day.

better focus on

Monday

Tuesday or Thursday. The difference was

(low barometric pressure) than on

statistically significant (p=0.01).

The subjects showed somewhat poorer focus on Thursday (high barometric pressure) than on Tuesday. However, the difference was not statistically significant. The

distribution for

Tuesday

Thursday was much wider

(std. dev. of

i 222

Lab Reports > Results

6 and

8, respectively).

(std. dev. of 12)

than for

Monday

or

Discussion

The "Reports"

section contains hard numerical data. In the "Discussion" section,

interpret that data, identifying

you

themes and helping the reader draw conclusions.

Begin your "Discussion" section with

a

reminder of the hypothesis. Then, indicate one of

the following opinions:

prove (or recommend) the hypothesis.

•

The experiment's

results

•

The experiment's

results disprove the hypothesis.

•

The experiment's

results

were inconclusive.

why you

Build a case for your opinion. For example, explain

think the results

recommend

the hypothesis. In building a case, answer questions such as the following:

•

What

•

Is

results

emphatically confirm your opinion?

there reasonable

doubt

for

your opinion? You are permitted the luxury of pointing

out possible flaws in the experimental design or holes in the results. •

How do

your

results

compare with

similar experiments?

Why

might your

results

differ?

Your discussion can optionally provide alternate interpretations of the data or

offer sug-

gestions for further research.

Discussion

Our team attempted

to

determine whether barometric pressure influences children's

ability to focus. In particular,

we

tested Tucker's (1999) hypothesis, which states that

children's focus correlates negatively with barometric pressure.

The

results

show

partial

significantly better

when

barometric pressure

is

support for Tucker's hypothesis. the barometric pressure

is

In particular,

low than they do

children focus

when the

neutral or high. However, children focused only slightly worse

during high pressure than normal pressure. The unusually high standard deviation on the high-pressure day (Thursday) suggests that high barometric pressure might affect

The

some

children greatly and others very

results suggest that,

little.

when diagnosing ADHD,

when barometric pressure

is

practitioners should give the

CPT

neutral.

The experiment covers only three

different days.

A more comprehensive experiment

should sample at least 10 different days.

Lab Reports > Discussion

223

Conclusion

Many

journals require a "Conclusion" section to summarize the results. At a

minimum,

the "Conclusion" section should provide reminders of the following information:

•

the hypothesis

•

the results

Some

scientists present ideas for future research in the

place these ideas in the "Research" section.

simply the

final

Some

"Conclusion" section, while others

journals require that the conclusion

paragraph(s) of the "Discussion" section.

Conclusion

Our team tested Tucker's (1999) hypothesis, which states that children focus better

when barometric pressure relatively high.

Our

barometric pressure focus worse

224

in

is

relatively low

than when barometric pressure

results found strong evidence that children is

relatively low.

However, our results did not find that children

high barometric pressure than they do

Lab Reports > Conclusion

is

do focus better when

in

normal barometric pressure.

is

References

Lab reports must contain appeared

a "References" section that

expands

all

the citations that have

in the report.

No Reference Format Different disciplines

Is

Truly Universal

impose

different journals within the

different

same

requirements for references.

discipline

sometimes impose

In

addition,

different

requirements.

The information provided on the best rule

this

page

is

generic. To prevent antagonizing an editor,

simply to copy the reference style

is

of previously

published articles

in

the target journal.

In

many

the

disciplines, a "References" section consists of a

numbered

list

For example, the

typically represent the order in first

"Reference" section

is

citation in the report

was

numbered

list.

The numbers

which the citation appeared for Tucker; therefore,

in

in the report.

element

[

1]

in the

for Tucker.

References [1]

Tucker, M.

J.

1999. "Focus and Weather,"

ADHD

Papers and Proceedings, 42, 526-

530. [2] Siska, N. S.

2003. "Temporal Focus Affect and Soft Drinks," Psychology and

Nutrition, 77, 215-223. [3]

Mackinson,

13,

482-491.

J.,

and

J.

Goldberg. 2004. "Temperature and Focus,"

In other disciplines, the "References" section also consists of a

author presents

list

elements

ADHD

numbered

Metrics,

list,

but the

in alphabetical order.

5gi

Lab Reports > References

225

Summary When •

of

Lab Reports

reviewing your lab report, ask yourself the following questions:

Who

the target audience for this lab report?

is

Does your

lab report hit the target

audience? •

Would

a

report?

Would

a

person reading the abstract understand what your experiment was

about?

all

•

person reading the abstract be tempted to read the remainder of the lab

Does your introduction provide for your target audience?

sufficient

background (or too much background)

Does your introduction cover previous research relevant

to this topic? •

Do

your "Materials" and "Experimental Procedures" sections describe the experi-

ment ran •

so precisely that other researchers could replicate the experiment exactly as you

it?

Does your "Results" section

faithfully represent the data collected in the

Have you checked the mathematical

results carefully?

experiment?

Are the graphs and figures mis-

leading? •

Does your "Discussion" section

indicate whether the experiment verified or vilified

the hypothesis? •

If

someone only had time

she get •

some

Does your "References" section target journal

"Conclusion" of your lab report, would he or

to read the

sense of what the experiment discovered? cite all relevant

research in the citation style that the

demands?

Grammar Many

journals require scientists to write lab reports

requires passive voice, you

must abide by

this style.

in

passive voice.

However,

require passive voice, then you should write the lab report In

nearly

all

in

if

If

the journal

the journal does not

active voice.

types of writing, editors are sticklers about maintaining a consistent

tense. For example,

most technical manuals are

Lab reports, however, are a strange within a lab report.

When

fruit.

written completely

in

present tense.

According to tradition, you mix tenses

describing the experiment (for example,

in

the

"Experimental Procedures" section) or previous experiments, use the past tense.

When

describing theories (such as "Tucker's hypothesis"), use the present tense.

1 226

Lab Reports >

Summary

of

Lab Reports

CHAPTER

16

PowerPoint Presentations

PowerPoint

is

the jacks-or-better of the corporate world

— you've got

to have

it

in

order to stay in the game. Just try giving a seminar without PowerPoint or showing

up

meeting with, gasp, paper handouts.

at a

be delivered as

a

broken PowerPoint

I

{Damn

stack.

live in

it.

my eulogy will

mortal fear that

Can't anyone get

this projector to

work?)

PowerPoint gives the patina of professionalism to even the most amateur presentation. few snappy bullet points,

a stately

background, and voila

PowerPoint presentations obfuscate lack of detail. Everyone

knows

it,

facts,

hide

evil,

—you've turned Fox

and

stifle

questions.

The

but everyone plays along anyway. Despite

devil

is

A

BBC.

into the

in the

you must

it all,

master the art of PowerPoint presentations.

When

asked to present some slides about your

research

and development, you might

grab the funding, or

The Golden Rule Your ideas

will

you

get

just

be

new

at a

bogged down

invention to the vice-president of

defining point in your career. Will you

in a

morass of mediocrity?

of Presentations

will fall flat

PowerPoint and the

if

you cannot keep your audience's attention.

CEO

unbelievable record-breaking fiscal

And thought, What we banned it. And we've had three quarters since we banned PowerPoint. Now,

would argue that every company

the world,

"We had

12.9 gigabytes of PowerPoint slides on our network.

huge waste

of

I

in

I

if

it

would

just

ban PowerPoint, would

see their earnings skyrocket. Employees would stand around going, 'What do

Guess

I've

a

corporate productivity. So

got to go to work.'" [Scott McNealy,

CEO

of

Sun Microsystems,

in

I

do?

an

August, 1997 interview with the San Jose Mercury Times.]

PowerPoint Presentations

227

r

Organizing a Presentation: The Big Picture

Table 16-1 provides a rough algorithm for organizing a short PowerPoint presentation.

TABLE

16-1

Approximate Division

of

Time and Slides

in

a Short PowerPoint Presentation

Approx. Percentage of Your Time and Slides

Section Introduction

5%

Body

75%

Conclusion

5%

Question-and answer (Q-and-A) session

10%

to

80%

to

15%

For example, in a 20-minute presentation, divide your time as shown in Figure 16-1.

Conclusion

Introduction

—

Q-and-A

i

16

1

Time

FIGURE

16-1

Time allocation

presentation consumes

If a

unit

own

its

in

(in

17

minutes)

a typical 20-minute presentation.

more than 20 minutes,

divide

it

into distinct units. Give each

introduction, body, and conclusion. In addition, layer in a brief introduction

and conclusion covering the whole presentation. For example, Figure 16-2 shows one way to organize a

one-hour presentation into three

Un

Global

t

Un it

1

units.

Un

2

r.3

Global conclusion

introdu ction

Bi 11:1 "

r

i

1

2

1

10

Time FIGURE 16-2

Time allocation

in

(in

minutes)

a typical 60-minute presentation.

i 228

PowerPoint Presentations > Organizing a Presentation: The Big Picture

I

58

1

60

The Number Asking how many

how many

lines

slides

of Slides

you need

is

kind of like asking

tion to answer this question precisely. Nevertheless,

you should estimate two minutes per rapid presentations, so

I

like to

one popular

slide. Personally,

I

the generic question,

isn't

rule of

enough informa-

thumb

states that

find that audiences prefer

more

slide include the following:

of audience

•

size

•

number of bullet

•

information density of graphics size

programmer

estimate around 80 seconds per slide.

Parameters affecting the time per

As the

a

of code do you need to write a program? There just

points per slide and

amount of text

of your audience increases, you typically go through slides

at a faster pace.

Large

audiences generally only interrupt your slides to ask questions during designated Q-and-

A

much less self-conscious about intermay take several excruciating minutes to get through controversial When audience members are highly familiar with each other, then the pace also

periods. Small audiences (seven or fewer) will feel

rupting you, and slides.

it

slows. For example,

if

you are presenting

to a

30-member

lab

team that has worked

together for several years, you can expect plenty of interruptions.

When

audience members

are primarily strangers to each other, interruptions drop.

Denser

slides

obviously take longer to consume, although sparse slides that require com-

pensating voice-over also consume too Slides that contain

complex graphics

much

time.

also take a long time to

consume. They

typically

require long-winded voice-overs. So, for example, a presentation that contains mainly

complex graphics might proceed

at a

pace of 5 or 10 minutes per

slide.

PowerPoint Presentations > The Number

of Slides

229

The Opening Moments

I

of a Presentation

cannot underestimate the value of a positive

medium

— from movies

to

PowerPoint presentations

—

few seconds, your audience start,

and your audience

first

impression. In every communication

stand-up comedy to newspaper

articles

few seconds are the most

and

right

back to

During those

the

first

will

decide whether you are worth their focus. Succeed

will root for you.

critical.

Screw up the beginning, and

you'll

first

the

at

be scratching

desperately for attention and approval. So,

how do you

succeed in the opening moments? At the risk of sounding

infomercial, the key

presentation sense

fear,

people;

is

is

confidence

—you must

valuable and that your ideas are

but audiences absolutely sense

3:00

like a

AM

believe in your heart of hearts that your

a lack

critical.

Dogs may or may not be

of confidence.

Humans

able to

attend to confident

the slick PowerPoint graphics won't bail the unconfident out of trouble.

all

Opening with a Joke

Some

people

tell

jokes well.

you are one

If

of

your presentation with a relevant witticism. little

levity

mood

room before

destined to

recommend beginning many presenters, a

rise

above the others. Your

be the one that people remember. Naturally, you have to

will

the

I

are one of

makes your presentation stand out from and

presentation of

those people,

When you

fall flat.

telling a joke; in

some

situations, attempts at

Generally speaking, though, the joke

your audience. Like most

gifts,

appreciate you just for trying.

it is

is

a

little gift

the are

you present to

the thought that counts— the audience

In fact,

sniff

humor will

the joke need not be particularly funny for you

to succeed.

Always beta-test your jokes. Nothing ruins a presentation faster than offending

someone in your audience. Make sure your beta testers include a wide range people. One of the safer domains is to poke fun at your own profession.

of

By the way, spontaneous remarks always get a bigger laugh than prepared ones. So, prepare

some spontaneous

remarks.

11 230

PowerPoint Presentations > The Opening Moments

of a Presentation

Introductory Slides: The Traditional Approach

moments

Since the opening

to this

know

approach

exactly

consider

The

a

as the

how

it is

is

to "tell

romantic-comedy

going to end

few examples of

slide in Figure 16-3

just

style

'em what you're going to

tell

'em."

I

tra-

refer

of overviews because your audience will

from watching the

first

few minutes.

We

will

now

this style.

direct

is

mean

The

are critical, your introductory slides better be good.

ditional approach to an introduction

and

concise, but

it is

someone were

suboptimal. The simple

title

("Intro-

come across this slide a few weeks after the presentation and read the title, would he or she remember what this presentation was about? What is this presentation really about, and why would an audience member duction") does not

want

to

pay attention to

anything.

If

to

it?

Introduction

My

presentation consists of the

following three parts: 1.

Hybridization

2

Genetic Modification

3

Biological

FIGURE 16-3

The

Nanotechnology

A suboptimal introductory

slide in Figure 16-4 offers a

more

which technical audiences usually

On this

like

slide.

In addition,

title.

and which

are a nice device for building excitement.

the downside, the second bullet point ("where we've been")

introductory

slide,

would you

contains date ranges,

instructive

really

know

is

it

a cliche. After

reading

the true purpose of this presentation?

Creating Fruit Species Technologies to create

new species

of

fruit:

- 1900 to 2000: hybridization - 1995 to 2010: gene modification - 2010 to 2050: biological nanotechnology This presentation examines where we've been and where we're going.

FIGURE 16-4

A better

title,

but too cliche.

PowerPoint Presentations > Introductory Slides: The Traditional Approach

231

On

the plus side, the slide in Figure 16-5 clearly states the purpose of the presentation (to

provide an overview of creating ever, this slide looks like

new

fruit species

with biological nanotechnology).

was written by someone

it

for a presentation to technical people.

To make the

audience, the writer should excise the

word

excited that he provides almost exactly the

which

who

is

a waste of the audience's time.

in marketing, slide

"exciting."

same words

The

which

both the

final bullet will

title

annoy

all

How-

the kiss of death

more appropriate

The author of in

is

for a technical

this slide

and the

is

so over-

first bullet,

audience members

are proponents of current technologies.

An

Exciting

New Approach

to

Creating Fruit Species This presentation examines an exciting

•

new way to -

Biological

create

new fruit species:

nanotechnology

We'll also explore what's

•

wrong with

current technologies.

FIGURE 16-5

The

Too "exciting" for a technical audience.

slide in Figure 16-6 has a solid title, a

good explanation of the

topic,

and

a straight-

forward approach that should appeal to a technical audience. The only negative

does not

tell

the order in

author must add

a

which topics

second

•

be presented. To remedy

slide that lists the

A New Approach Fruit

will

this

order of presentation.

to Creating

Species

how our species with biological nanotechnology. This presentation explains

team plans We'll

to create

fruit

compare our approach

hybridization

FIGURE 16-6

and genetic

to

modification.

Best of the bunch.

11 232

is

that

problem, the

PowerPoint Presentations > Introductory Slides: The Traditional Approach

it

Introductory Slides:

An

alternate

tell

'em."

I

approach

refer to this

approach as the mystery

a surprise

just the right

and then layering

appeals to scientists since their

gambit

life's

work

style

is

is

to "tease

'em what you're going to

of overviews because you withhold

moment. You can

in clues as

Figure 16-7, which uses mystery

in

Alternate Approach

for writing introductory slides

important pieces of the plot until

by promising

An

build tremendous interest

you proceed. This technique often

essentially solving mysteries.

Consider the

style.

A New Technology for Creating Fruit Species Our team has a novel approach, which this presentation will uncover.

compare our approach

We'll

hybridization

FIGURE

16-7

to

and genetic modification

Use mystery techniques

enough

to build suspense.

members

The

title is

clear

first

bullet

announces the purpose without giving away the punch

to reassure audience

naturally curious species,

and

The

laying out

secret

line.

Humans

humans are even more so. The audience wants to Of course, the secret won't be found on the next

must be nurtured while you gradually uncover

clues. Occasionally, while

background information, you should remind the audience of the ultimate

as in the final bullet

The

are a

intelligent

get to the next slide to learn the secret. slide.

that they are in the right place.

goal,

of Figure 16-8.

Genetic Modification:

Summary Pros:

- Desired traits in a single generation - More predictable than hybridization

Con: - Expensive

Our new approach minimizes the expense

FIGURE 16-8

In the perfect

Remind the audience

that the secret will be revealed

later.

mystery presentation, you can slowly lead the audience to come to the same

conclusions that you did.

PowerPoint Presentations > Introductory Slides: An Alternate Approach

233

Body

Pace and Variety

Slides:

Modern audiences have extremely

short attention spans. Very few people can attend to a

speech for longer than 20 minutes, and after

only 5 or

10.

When

dull very quickly.

many

To audiences raised on

attendees will be taking mental vacations

television clickers,

giving an hour-long presentation,

PowerPoint presentations get

how do you

avoid just talking

to yourself for the last 40 minutes?

To hold an audience through an hour-long presentation, you must switch focus every 15 minutes or

so.

After presenting a series of slides, get the audience to

do something;

for

example, consider the following ideas: •

Ask them questions.

•

Do

•

Challenge the audience to solve

an informal survey. a

problem or

go into

let

the audience's eyes rest

a trance rather readily. Feel free to

brainstorm ideas.

between the projection screen, you, and

In general, keep the audience's attention cycling

themselves. Never

to

on one spot

dim

lights to force the audience's focus to change. Prepare for

some

to

same

mix

that a professional presentation requires that

length. In fact, this

all

have approximately it is

better

a Presentation

Teachers and seminar leaders are well acquainted with "death

between 30 and 90 minutes presentation. Seated adults

after lunch. This will

sometimes

avoid early morning presentations

The best time 11:00

AM)

of

day

to present information

bad news or speaking

do not

is

which strikes

asleep during this period. Similarly,

fall

is

valley,"

the worst time of day to give a

when speaking

or two to three hours after lunch.

after lunch,

Finally,

slides

not optimal. To keep your audience's attention,

is

the length of slides; in other words, after a few long slides, insert a short slide.

When to Make

to teenagers.

mid-morning (perhaps 10:00

On

the other hand,

if

AM

to

you are presenting

to an oppositional audience, schedule your presentation just

when people tend

rely too heavily

to be at their

on

bulleted

most

lists.

relaxed.

Make

sure that your slides

of graphics, tables, and charts.

234

and turn up the

bland stretches by interspersing

interesting digression slides or examples.

Many people feel the

for too long; intelligent people

the projector occasionally

PowerPoint Presentations > Body Slides: Pace and Variety

mix

in plenty

Mechanics: Fonts and Backgrounds

Many

presenters obsess about mechanical points such as the appropriate font and back-

grounds

on

to use

many people

slides. In fact, this

use before buckling

is

one of the

down and

classic procrastination

techniques that

writing the copy for those blasted slides.

Don't waste your time worrying about fonts. PowerPoint provides excellent defaults for fonts

and font

sizes. If

you

feel a

strong need to use a nondefault slide template, create one

that uses a sans-serif font. Note, however, that the printed version of PowerPoint slides will

look better with serif fonts. For more information on fonts, see Chapter

Many companies and If,

is

conferences mandate the background for PowerPoint presentations.

however, the choice for backgrounds appropriate for your audience.

sider unintrusive designs with

ence, find a

more

When making a

If

is

yours, don't just pick a pretty one; pick one that

your audience

muted

colors. If

you

is

fairly

stodgy and conservative, con-

are trying to appeal to a

younger audi-

vibrant background.

long presentation, consider color-coding different categories of slides. For

example, you might paint a light

19.

a light

blue background for

all

green background on

slides

all

slides

containing exercises and

containing digressions.

For a multiunit presentation, consider giving each unit a distinct background image. For

example, each

slide in the unit

on hybridization might contain

a

background image of a

pea plant, while each slide in the genetic-modification unit might contain a background

image of

a

microscope.

1* PowerPoint Presentations > Mechanics: Fonts and Backgrounds

235

Body

Slides: Effective Lists

Chapter 7 discusses

lists.

Beyond

the general

recommendations about

lists in

that chapter,

consider the following additional suggestions for PowerPoint: •

Place rules before examples; in other words, define a rule

and then supply examples

to support the rule. •

Ensure that second-level bulleted items follow naturally from their

•

Minimize the number of

•

Keep each element

The

list

items

at

first-level superiors.

the third level.

fairly short.

slide in Figure 16-9 violates

most of these

rules.

Making Citrus Hybrids Example, the tangelo

is

a cross between a

pummelo or grapefruit and a tangerine. There are many varieties of tangelos and all are much sweeter than pummelos or grapefruits. - Some •

varieties,

The ugh

fruit is

such as

ugli,

are chance crosses

a cross between a mandarin orange and

a grapefruit

Most varieties of citrus can be crossed produce new varieties.

FIGURE 16-9

The

A

slide with

problematic

slide in Figure 16-9 contains

following

•

The

to

lists.

some

fine facts;

however, these facts are defeated by the

faults:

title is

misleading;

it

suggests that the slide will explain

how

to

make

citrus

hybrids. •

The opening dense

•

bullet

is

a borderline

run-on, which makes the entire slide a

bit too

visually.

The second-level

bullet

("Some

varieties...")

does not follow logically from

its

supe-

rior bullet. •

The

•

Examples are wonderful, but the general principle ("Most

third-level bullet

crossed...")

236

is

an unnecessary digression. varieties

ought to precede the example rather than follow

PowerPoint Presentations > Body Slides: Effective

Lists

it.

of citrus can be

The

slide in Figure

will

somewhat

is

cleaner

Crosses Easily

Citrus Citrus

16-10

cross with most other citrus

- Most crosses are intentional - A few famous crosses are accidental

Most tangelos are - Tang erines

x

Ugli fruits are accidental

- Mandarin orange

FIGURE 16-10

The preceding

crosses

intentional

pumm elos crosses

x grapefruit

A cleaner

set of

slide focuses

lists.

on

the key points (citrus crosses through intention or accident)

and provides supporting examples (tangelos and

ugli fruits).

The

original slide

mentioned

the sweetness of the resulting fruit, but that fact was off topic, so the preceding slide

omits

The

it.

slide in Figure 16-10

nate approach

is

to

still

chop the

contains too

much two

single slide into

information for some viewers.

•

Place the rule (crosses are intentional or accidental)

•

Place the examples (tangelos

Yet another

approach

is

and

The downside

to this

approach

is

The

slide

on

alter-

on one

slide.

the next slide.

might look

that audience

won't have a record of the example

Citrus

ugli fruits)

to use a single short slide that focuses

voice provide details of the examples.

An

slides as follows:

on the

like that

rule

and then

shown

let

your

Figure 16-11.

in

members who look back on

their slides

details.

Crosses Easily

Citrus usually crosses with other citrus varieties

- Most crosses are

intentional; for

example,

tangelos

- A few famous crosses are example,

FIGURE

16-11

accidental; for

ugli fruits.

Focus on the

rule in the slide; provide

more examples

in

speech.

PowerPoint Presentations > Body Slides: Effective

Lists

237

Audience: The Theory of Relativity

Your presentation's content and tone should depend on where you are relative to the

If

the Audience

Many

in the organization

people in your audience.

Is

Mainly above Your Level

presenters mistakenly believe that higher

management has more

technical knowl-

edge than individual contributors. Although some high-level managers do retain their engineering

most high-level managers

skills,

lose technical skills rapidly

when

they stop

using them day to day. High-level managers get paid to siderations. Focus

revenue will this provide?

•

How much

will this cost to

•

How much money

From manufacturing

If

critical decisions, typically

How much

•

up

make

in response to

the Audience

based on financial con-

your presentation on money, answering questions such

produce?

will this save the organization?

to biotech to nonprofit, high-level

money and

Is

as the following:

manager

ears typically only perk

schedules.

at Your Level

Individual contributors talking primarily to other individual contributors should focus technical details. Slap

on an

extra coat of jargon,

financial considerations; just get to the

ence to stumble

If

the Audience

If

you

are a

is

Is

good

Beware

that this

slides to is

the

most

your underlings, your audience may she holding this meeting?

are also nervous about being put to start the

on

the spot.

To

meeting with a perfunctory

get

PowerPoint Presentations > Audience: The Theory

Is

likely audi-

feel a certain

my job okay? Audience

your audience

all is

is

238

is

on

Ignore

below Your Level

They may wonder, Why

sometimes smart

stuff.

rolling.

a rathole, so be prepared to shut off worthless debates dictatorially.

manager presenting

sense of fright.

members

down

and keep the nerd-speak

of Relativity

well.

to listen,

it

Graphics

Most audiences view graphics long hours to prepare.

If

as a treat.

However, graphics are an expensive

you have the time though, graphics do jazz up

a

gift,

taking

PowerPoint

presentation.

Although

must slide

a truly gifted artist

learn to provide a is

okay

if

a story entirely

tell

text.

The graphic

•

The

is

is

text

slides, the rest

of us

and graphics on the same

relatively simple.

brief

and supports the graphic.

For example, the slide in Figure 16-12 meets both

R&D:

through graphic

Mixing

the following criteria are both met:

•

text

can

mix of graphics and

criteria.

Patent Production Patents have

moie

m (lie

than doubled last tliiee

\e;u*

In late 2003,

we

doubled oui investment in

FIGURE 16-12

If

Simple graph and simple

either the graphic or text

on

is

R&D

text

shown on the same page.

more complex than those shown Figure

16-12, place

them

different slides.

Beware

of Cliche Clip Art

A number of years ago, the novelty guy is shocked by our first quarter numbers, too.) Today, though, the included clip art strikes most audiences as somewhat amateurish and cliche. All clip art is not bad. However, audiences now PowerPoint provides a widely used set

of clip art

appealed to audiences.

of clip art.

(Wow— that

clip art

expect more than stock cartoon characters.

PowerPoint Presentations > Graphics

239

The Complexity

Before creating graphics, consider tion.

•

Graphic

of a

how your

Will the presentation be projected

on

view the PowerPoint presenta-

will

on

a high-quality screen,

or will

it

be projected

a wall? Is the wall a bright color?

•

Will your audience be close enough to view details in the graphics?

•

Will you be able to point (with a light pen or stick) to selected details in the graphics

while giving the presentation? (This

One

always handy.)

is

of the classic mistakes in creating graphics for PowerPoint

detail, particularly

ence to notice

when

detail. In

the viewing conditions

slide,

which

detail in

reasonable formula for good graphics slides

paragraph of

slide

is

providing too

Think

it

far

if

as follows:

amount of detail

in

much

if

you need

to speak

it.

explanation, break

it

into

two or more

slides.

PowerPoint Presentations

presenters hand out hard copies of their slides to the audience so that their

audience has something to write on when trading e-mail addresses and stock Unfortunately,

in

hard copy, the graphics

in

hard-copy versions of slides are truly important,

PowerPoint Presentations > The Complexity

tips.

PowerPoint slides are often hard to read. try to

keep the graphics simple.

Hi 240

too long

through:

should hold approximately the same informational content as one

graphics slide requires too

Printed Graphics

If

much

your graphics.

In other words, a graphics slide has about the right

Many

is

almost impossible for your audi-

text.

about one paragraph's worth of words to explain If a single

it

also frustrates the audience.

viewing conditions are poor, reduce the

One graphics

make

such situations, frustrated speakers end up spending

explaining each graphics

A

audience

Ask yourself the following questions:

of a

Graphic

Question-and-Answer Sessions

your audience

In a successful presentation,

can also be

you

a sign that

will ask lots

of questions. (Lots of questions

aren't explaining things very well, but we'll

hope

that this isn't

the case.) Questions indicate interest. In addition, the rapid shift of focus between pre-

senter for

and audience makes

Q-and-A If

•

it

harder for audience

members

to

daydream.

Two

strategies

logistics are as follows:

you are speaking to

a small audience, invite

them

to ask questions

throughout the

presentation. Encouraging questions helps keep your audience engaged. •

If

you are speaking

to a large audience, urge

end of the presentation; however, session at the

The Q-and-A

end of each

session frightens

if

them

some

presenters. After

can occasionally turn hostile. For best

sion just as you

would prepare

a small

group of colleagues, and

practice session

is

all,

there

is

no

script for

prepare for the

results,

for the rest of your presentation. Practice invite

them

to ask questions.

these questions so that you can polish your answers

If a live

on questions

lengthy, provide a

is

until the

Q-and-A

unit.

tion, questions

on

to hold off

the presentation

it.

In addi-

Q-and-A

ses-

your presentation

Have someone record

later.

not a possibility, you must imagine the questions that will be

asked and prepare answers for them. Visualize your toughest

critic

(That jerk!) trying to

pick your ideas apart. Practice your answers for the worst-case questions. You'll sleep better the night before.

Keep your answers short and focused a question, as this will grease the

answer, say

so. If

you are taking an educated guess, say

Okay, you have done

all

your homework and are ready

no one asks anything. This, prepared with a

— never ramble. Thank

wheels for subsequent ones.

list

too,

The

Q-and-A

and

question of a

few

moments of any

of ending with a truly

final

questioner for asking

truly

do not know

the

on

all

questioners and then...

slide.

Turn the

tables

on your audi-

session typically concludes the presentation. However, the

questions might wander off the last

first

you

so.

to take

of dialog starters on an emergency

them questions.

final

If

can be rather uncomfortable. The wise presenter comes

ence, and start asking

final

the

mark or

into minutia.

Note that the

first

few

moments

presentation are particularly important. Therefore, instead

question, you should consider ending by displaying a final slide that

wraps up your presentation.

PowerPoint Presentations > Question-and-Answer Sessions

241

Different Kinds of Learners

most people have

Just as

acquire knowledge

more

to gather information

When be

a

most people

style. In brief,

dominant hand, most people

naturally through

What makes

this

you can speak

book)

is

that

even trickier

auditory learners prefer

see;

is

you can simultaneously

slides

learners,

opposed

to either a

much higher much faster than

that the visual presentation proceeds at a that

is,

people can read text

you should always provide

a

sound

track;

you may not simply

up on the projector without providing any commentary. To

you should always provide

without supporting tracted

(as

cater to both kinds of learners.

it.

cater to auditory learners,

with

what they read or

giving a PowerPoint presentation to a group, both visual and auditory learners will

bandwidth than the auditory presentation;

throw

dominant learning

through what they hear.

your audience. The value of a PowerPoint presentation

in

straight lecture or a

To

also have a

are either visual learners or auditory learners. Visual learners

slides.

slides;

cater to visual

you should not present new material

To complicate matters,

orally

a percentage of visual learners are dis-

by auditory input. (Not everyone can read when music

is

on, particularly music

lyrics.)

Within the broad group of visual learners, some learn more readily from pictures than

from

text.

a nice

Like a polite host offering a variety of dishes to suit

mixture of graphics and

When the Audience Your audience

is

Is

many

One

not always a group. Sometimes, your audience

person— often your

palates, try to provide

text.

is

just a single

supervisor. In this case, the wise presenter studies the target's

learning style.

Does your in

person?

target generally ignore your e-mail, preferring to get information from you If

so,

your target

is likely

an auditory learner. Do not waste too

writing elaborate slides; she won't read

Does your

target tend to ask you for written

meetings or

insist that

visual learner. details will

A

go a

everything be written

crisp executive lot

summary

summaries following face-to-face down? In this case, your target is

likely

page, followed by supporting pages of

further than blah blah blah.

11 242

much time

them anyway.

PowerPoint Presentations > Different Kinds

of

Learners

a

PowerPoint Speech: The Basics

Many

technical presenters put far too

enough time

into practicing

improving the "sound track"

You must •

to

time into perfecting slides and not nearly

The next few pages provides advice on

will say.

your PowerPoint presentation.

perfect the following basics:

first

Speak loudly enough to be heard. Project your your voice

•

much

what they

Speak

to the

clearly.

voice.

Imagine that you are launching

back row.

Enunciate the

final syllable

of each word

— make sure you catch

all

the

consonants. •

Make eye contact with

different people in different parts of the

room.

frightens you, stare at foreheads instead of eyes. (Your audience won't

If

eye contact

know

the

difference.) •

Stand up straight. Don't slouch. Square your shoulders. Bend your knees

slightly.

Breathe. •

Drink something warm (not hot)

When

I

Turn on the Projector, You Will

just before speaking.

Fall into

Never drink

ice water.

a Deep and Satisfying Sleep

Your listeners, no matter how well educated, have a very short attention span. You are at war to keep their focus. To win the battle, avoid entrancing your audience. Just

about any form To fight •

it,

of repetition

can put intelligent audience

members

into a mild trance.

you must seek discontinuities by altering the following:

The speed

of your delivery.

Slow down once

in

a while,

and speed up once

in

a

while. •

The volume

of your delivery.

Emphasize points by

raising or lowering your

voice. •

The body motions

of your delivery.

hands rhythmically.

Never rock rhythmically. Never move your

Feel free to walk around, particularly

if

you are using a

wireless microphone. If

you must hold an audience's attention

minutes or

for a long time, try to

change topics every 15

so.

PowerPoint Presentations > PowerPoint Speech: The Basics

243

PowerPoint Speech: Lessons from the Pros

You don't have

to be a superstar

theless, technical speakers

your

listeners as

performer to deliver

a

good PowerPoint speech. Never-

can benefit from the secrets of professional entertainers.

1

Treat

an audience whose attention you must hold. Learn to engage your audi-

ence. If you don't have their attention, your message will be lost.

These Tips Aren't for Every Audience

As with any form

of

communication, you must know your audience.

which you are speaking suggestions.

If,

is

very conservative, then beware of

however, the forum

is

somewhat more

many

If

the forum at

of these

casual, then take these

suggestions seriously and emerge as the audience's favorite presenter.

Lesson

1:

Entertainment Pros Provide a Pre-Show

A pre-show

is,

not surprisingly, the information that precedes the show. All forms of pro-

fessional entertainment provide a

pre-show to build an audience and to build excitement;

for example, consider the following:

•

Movies provide

•

Theatres provide playbills.

•

Television provides teasers and ads.

trailers.

Technical speakers can sometimes provide a pre-show. Your pre-show might take the form

of an e-mail to your audience. Perhaps you'll have someone distribute interesting handouts related to your presentation a few

minutes before you speak. Perhaps these handouts

will

suggest something intriguing or puzzling.

Get the audience to anticipate your speech before you say your

Lesson

2:

Again, the beginning and ending of any presentation

are the

most memorable moments. Therefore,

such as

a fascinating revelation

thing exciting but don't deliver

I

word.

Pros Deliver a Grand Finale

Good shows end with something big.

1.

first

developed

this

chunk from

try to pull off a surprise just near the end,

from your research. Better

on

it

until the

my experience as a

yet,

promise your

end of the presentation.

professional juggler.

I

244

PowerPoint Presentations > PowerPoint Speech: Lessons from the Pros

listeners

some-

—

Lesson

Many

3:

Pros Study Their Body Language

professional entertainers watch tapes of themselves. If you have never seen a tape of

yourself giving a presentation, you should endure discover. For this

is

added

thrills, invite

some

just as "natural" a process as

While watching the

tape,

it

soon. You will be amazed

at

what you

friends to review the tape with you. Don't

having

a friend edit

compare your body language with the following

•

Stand up straight but not too

•

Lean forward

•

Project confidence by keeping your

worry

your writing. ideals:

stiffly.

which projects energy and enthusiasm.

slightly,

body expressions expansive and open. Never

hunch your shoulders. optimism by moving your hands upward.

•

Project

•

Move around

•

Don't

feel that

you are

Move your hands

a bit. Just don't flap

Always

in

from

your hands enough

podium when

your audience are highly attuned it.

Some

whether you believe

will

to

it is

go into

to

is

the

flight.

most important

your turn.

body language and

be trying to detect whether you are

what you are saying. Therefore,

in

podium. You can even move

beginning of any presentation

stride confidently to the

sorts of clues

tied to the

to time.

earlier in this chapter, the

Some people least

little.

from time

As noted part.

a

into the audience

tell

will pick

up

telling the truth,

the truth

and

all

or at

believe in

what you are saying.

The Mute Button: Your Best Instructor

Would you like some help on body language? Consider watching television with the sound off. Watch your favorite comedians, and see how they invite you in through relaxed body gestures. Watch politicians try to convince you of their point of view through persuasive hand motions. Watch how the posture of news reporters conveys gravity or intensity.

Lesson 4: Pros Consider Costuming Professional entertainers consider what to wear.

tume

They

try to figure out

what kind of cos-

will help their presentation.

Believe

it

or not,

some engineers and

course, most engineers ever, for those

few

and

in the

scientists

do attend to what you are wearing.

scientists take a certain pride in their fashion blindness.

Of How-

audience that do care about your clothes, try to figure out which

clothes will help your cause.

1

PowerPoint Presentations > PowerPoint Speech: Lessons from the Pros

245

PowerPoint Speech: Overcoming Fear

If

you

that

thumbing through

are

you turned

of public speaking. Climb a that

If

book

in a bookstore, then there

cliff?

No

all,

a

is

a

mighty good chance

stunning percentage of people are afraid

problem. Explain to an audience

how you climbed

Terrifying!

cliff?

the fear of public speaking

with

this

directly to this page. After

is

limiting your career, you should strongly consider working

speech coach or possibly some sort of behavioral therapist (such as a

a professional

hypnotist).

Many speakers They

— they are afraid of freezing up and having a panic attack.

fear the fear itself

certainly

common

fears,

but you should

know

the following

two

of them. These are

less

facts:

•

Even most professional performers experience stage

•

Experimentation strongly suggests that a certain amount of fear actually helps your presentation. This "fear" a

The

and think

are also afraid that the audience will detect the fear

our way of getting our bodies ready

to be

best

way

to

overcome

again. Practice it

right before

it

if

fear

is

to practice the audio portion of

when you

you go

that an audience helps the

other words,

are in the shower. Practice

to sleep.

The

social psychologist

when

your presentation over

when you

are in the car.

Robert Zajonc has noted

dominant response and hurts the nondominant response.

you truly know your speech, you

an audience than

it

will

probably deliver

it

alone. Conversely, delivering an unpracticed speech in front of an

Practice Relaxing

You have undoubtedly heard someone Everyone knows

it

tell

you to relax by taking a deep breath.

works, but most people forget to breathe

when

tense. To force

those soothing breaths, consider the following two techniques: If

you

will

read from notes, write the stage direction "[deep breath]" at the end

of every paragraph. In other words, script •

If

you

will

246

then

your breaths.

speak without notes, then when practicing, remember to practice

taking a deep breath at the will

In

better in front of

audience often leads to poor performance.

•

for

peak performance.

and over Practice

would seem

fright.

become

just as

same

points

in

your presentation. The deep breath

automatic as the rest

of

your speech.

PowerPoint Presentations > PowerPoint Speech: Overcoming Fear

Summary The

PowerPoint Presentations

of

night before giving your big PowerPoint presentation, obsess over the following

questions:

•

Have you rehearsed the

•

Is

interesting? •

If

Are you opening with

your presentation

Are your slide?

Does each section contain

slides well organized?

Are the

Are any of the bulleted

•

Do

Does each

•

Have you

•

Is

items run-ons?

list

and graphics on each

fixed

all

Are your

first

words

a distinct

slide follow naturally

beginning and end?

from the preceding

organized into discrete sections?

slides

•

the text

long.)

appeal to your audience?

a joke? Will that joke

longer than 15 or 20 minutes, have you divided your presen-

is

tation into discrete sections? •

Have you rehearsed multiple times?

entire presentation?

your opening strong? (Note that I'm saying strong, not

spelling errors

slide

Do any slides

make

contain too

many

list

items?

sense?

and typos?

your presentation appropriate for your audience? Will supervisors or underlings

take the presentation the right way? •

Do

•

Can your graphics be

•

Do you

•

Will you be nervous?

Finally,

•

•

any of your graphics require more than

minute of explanation?

have a convincing and memorable conclusion?

consider

Where

a

seen from the back of the room?

is

a

If so,

do you have

scheme

for fending off panic?

few practical matters:

the printed material?

Does the microphone work? clothes will you clip

•

Do you know how

•

What

will

a

it

to

on

Where

Is it

are the notes?

a clip-on

Where

microphone?

are the slides?

If so,

what part of your

to?

work

the projector?

you wear?

Sleep tight.

PowerPoint Presentations >

Summary

of

PowerPoint Presentations

247

CHAPTER

17

E-Mail

any e-mail messages t

A,

engineer

—

—even those sent by one

brilliant

engineer to another bri

are unintelligible. This chapter focuses

on writing

effective

e-m mail messages.

'

Pickford Paradox of E-Mail

Mary Pickford— talented,

intelligent,

and charming— was a Hollywood superstar

during the silent film era. After the advent of "talkies," Pickford noted that talkies

were

artistically inferior to silent

movies. Therefore,

in

her opinion, silent films should

have come after motion pictures with sound. Critics referred to her idea as the Pickford Paradox.

As a

scientist or engineer,

ridiculous. After to a

all,

you might be thinking that the Pickford Paradox

when would

higher-bandwidth

medium

a lower-bandwidth

medium

(silent films)

is

be superior

(talkies)?

The strange answer is that we are living through a Pickford Paradox of our own now. The bandwidth of a telephone call far outstrips that of an e-mail, and yet, corporate employees now communicate more through e-mail than through the telephone. Imagine

telephone

if

e-mail had been invented

the 1970s.

in

If

that

in

right

the nineteenth-century and the

had happened, we would probably

the power of the telephone. (Wow, you can have a conversation

still

in real

be amazed by time with your

voice!)

Even more fascinating, the effective bandwidth of zero. That's

many

e-mail messages

is

exactly

because many e-mail messages are so poorly written that no information

actually gets

communicated.

E-Mail

249

The Essence Tom

researched

of the E-mail

some software

Problem

and then used Microsoft Word

tools

to

compose

the fol-

lowing short, formal document:

Recommendations

Sam one

asked

me to

for

Performance-Analysis Tools

investigate various performance-analysis tools

thought was best suited

I

explains

for

and recommend the

our department's needs. This short document

my methodology and recommendations.

Methodology I

I

downloaded evaluation copies

of the following three performance-analysis tools:

•

Kaneval Eval v8.2 (made by Dexco Unlimited)

•

Pert Burner v3.1

•

PerfRomance v5.0 (made by Carambola Software)

used

all

(made by Dexco Unlimited)

three tools to evaluate our latest software release, going through the

documentation and trying out various features. Recommendations I

strongly

recommend PerfRomance

v5.0 over the two Dexco Unlimited products for

the following reasons: •

PerfRomance

•

PerfRomance generates the clearest

the easiest product to learn.

is

reports. (I've attached

some comparable

reports.)

PerfRomance has the lowest

•

In a parallel universe,

up

his

To:

Sam

recommendation

cost.

researched the same software tools. However, instead of writing

as a formal

document, he composed the following e-mail:

EngTeam

Subject: Recommendations

PerfRomance was very clean compared to the other two. --Sam

1

250

E-Mail >

The Essence

of

the E-mail Problem

Sam's e-mail message

is,

admittedly, concise, but the message

message doesn't contain any supporting

detail.

Engineers are

is

fuzzy.

critical

Furthermore, Sam's

thinkers

who

require

substantiation of any claims.

Something strange happens

to people

when

they compose e-mail. Even

same

brings great discipline to the art of writing formal documents, that

vanishes in the writing of e-mail.

busy people write e-mail

Some

of

my own

When composing

if

an engineer

discipline usually

e-mail, people get very sloppy.

Many

as a stream-of-consciousness exercise, just blasting out messages.

e-mail messages have as

as the chaotic brain pattern

I

much coherence (and

I'm a professional writer)

experience just before falling asleep.

much lower expectations from e-mail than from many people write e-mail to those low expectations,

People have

formal documents. Conse-

quently,

forfeiting

they have about good writing.

The

first

all

the

rule of writing work-related e-mail

is,

knowledge therefore,

as follows:

Use the same

The preceding

discipline

rule will

ning e-mail through /

in

sound

writing e-mail as you

trite until

you give

it

do when writing formal documents.

a try.

The same

a spell-checker, capitalizing normally,

discipline includes run-

and even putting the pronoun

in uppercase.

Note that I'm only talking about work-related information. I'm not saying that messages like the

To:

following deserve any discipline at

all:

EngTeam

Subject: Lunch

Lunch at Mary Chung's at noon today?

--Sam

I Ilk E-Mail >

The Essence

of the E-mail

Problem

251

Before Hitting the Send Button.

If

I

were king of the world and the world had

institute the following rule,

may

You

When

which

I

believe

fallen into serious

would

not send any e-mail until you have

economic

collapse,

I

would

increase gross world product immensely:

reread

first

it.

rereading your e-mail, always ask yourself the following question:

Will the recipient(s)

For example, suppose

understand

this

message?

Sam (based in London) sends out the who has just joined the project:

following message to Nicole

(based in San Francisco),

Nicole

To:

Subject: status reports

status report needed by end of day tomorrow

At

first

glance, the preceding e-mail message seems innocuous enough. However,

poor

Nicole will probably not understand this message for the following reasons: •

Like

many e-mail

sentence

is

messages, this message

is

written in passive voice. In

fact,

the sole

missing a pronoun altogether. Consequently, Nicole cannot be quite sure

whether she needs

to

produce the status report or Sam needs her input on

his

own

status report. •

Since she just joined the project, Nicole probably has

report

is

required.

Sam should send

no idea what kind of status

Nicole a status report template or an example

status report. •

The phrase end of day

is

ambiguous. Sam's end of day

(in

London) comes quite

a

few hours prior to Nicole's. •

Engineers and scientists have an extremely low tolerance for empty bureaucratic exercises. Since

Sam does not explain the purpose of the status reports, amount of effort into producing them.

not put the appropriate

252

E-Mail > Before Hitting the

Send Button.

Nicole might

The message

•

is

missing uppercase

letters

and punctuation. I'm not

a literary scholar,

but I'm reasonably certain that most of the best writers' start sentences with an

uppercase

As

is

letter

and end them with

a period.

often the case with e-mail, Sam's original message omitted critical details and lacked

any sort of empathy with the recipient. have solved the problem.

To:

A

Sam would do

brief

moment

of reflection on Sam's part would

better to send the following e-mail instead:

Nicole

Subject: Please send me

a

status report

Please write a status report and send it to me by 10:00 am (your time)

Thursday, Nov. 30. Your status report should contain the following two sections:

*

"What

I

Accomplished This Month"

*

"What

I

Plan to Accomplish Next Month"

For each section, provide

a

bulleted list containing three or four items.

like brevity, so try to keep each item down to a sentence or two.

attached

a

I

I've

sample status report.

Everyone in my group writes

every month.

I

a

status report on the last working day of

use these status reports to produce

for my own manager.

In addition,

I

and use items from them in your annual

If you have any

a

monthly status report

store all your monthly status reports

salary review.

questions, don't hesitate to send me an e-mail or call me.

--Sam

1.

One

e.e.

of the primary reviewers of this book (Chris Sawyer-Laucanno) published

cummings, who famously eschewed

However,

in e.e.

cummings' personal

capitalization

letters (the

a

biography of the poet

and sentence-ending punctuation

in his

poems.

e-mail of his time), he did use traditional capitalization

and punctuation marks.

..-

E-Mail > Before Hitting the

Send

Button...

253

After the First Miscommunication.

When composing would never say

e-mail, people are often blunt.

People are

in person.

much

They type

wiser (or

things in e-mail that they

more cowardly)

in face-to-face

or

telephone meetings than they are while composing e-mail. Therefore, before hitting the Send button, ask yourself the following question:

Would you

feel

comfortable saying the text

in this

e-mail

message

in

a face-to-face

meeting with the recipients?

The preceding question really

have to take

a reasonable starting point for e-mail sensitivity; however,

is

a step further. After

it

all,

whole range of social cues, including body language, tions. In a face-to-face meeting, attendees

you

in face-to- face meetings, listeners attune to a facial expressions,

know whether you

and vocal

inflec-

are being sarcastic, but

e-mail recipients might easily miss the sarcasm.

Emoticons

Emoticons are graphics that come

in

either of the following two forms:

new-fangled graphic icons, such as the following which are quite popular

•

in

instant messaging:

old-fashioned collections of punctuation marks, such as

•

The

oft-stated purpose of

emoticons

is

:)

to provide emotional context for instant

messaging and e-mail messages, since words alone allegedly cannot do the

trick. For

example, notice how the following emoticons defuse a potentially sticky situation:

You're an idiot.

:

)

You have no idea what you're talking about.

Your experimental design is juvenile.

My

initial

:)

:)

response to emoticons was that writers have

somehow managed

to

convey

emotional context through words alone for several millennia. (Astonishingly, the

works I

now

of Tolstoy,

realize that

instant

Shakespeare, and Cervantes do not contain a single smiley face.)

emoticons can be a valuable means

messaging

if all

recipients share a

common

Note that many older readers are not well versed

in

of

expression

in

emoticons and may

annoying and confusing.

Do

not place emoticons

in

any formal or

legal written

1; 254

E-Mail > After the First Miscommunication.

e-mail and

understanding of their meaning.

communication,

find

them

Miscommunication

in

e-mail often generates rage. For example, consider the following

e-mail message, which does not successfully convey the intended idea:

EngTeam

To:

From: Quincy (QA Manager)

Subject: Performance Testing on Project Sea Grape

I

ran performance tests on Project Sea Grape over the last week.

I

found

performance at the expected levels, except for the Batch Processing Module.

The preceding message angered Tim, who wrote

the Batch Processing Module.

He was not

only angry, but he was embarrassed because Quincy had sent out the e-mail message to the entire engineering team.

Tim responded

in the following

way:

To: Quincy

EngTeams

CC:

Tim

From:

Subject: RE: Performance Testing on Project Sea Grape

There is nothing wrong with the performance of the Batch Processing Module. In

fact,

it

outperforms earlier releases by

a

factor of three. How did you

test it? Do you have any previous experience writing tests on Batch

Processing Modules?

In typical

work environments, Quincy and Tim would

get into a rapidly escalating e-mail

war, with each side accusing the other of greater and greater ignorance. However, is

Quincy

not a typical engineer. Instead, he obeyed the following principle:

After the first

miscommunication, stop sending e-mail. Use other media instead.

Tim on

Quincy

called

cessing

Module performed

the telephone to apologize. far better

out a clarification to the entire EngTeam mailing Scientists

and engineers are more

Quincy had meant

than expected.

Tim was

relieved.

that the Batch Pro-

Quincy then sent

list.

sensitive than stereotypes suggest.

E-Mail > After the First Miscommunication...

255

Summary When

of E-mail

reviewing an e-mail message, just prior to clicking the Send button, ask yourself the

following questions:

•

Will the recipient(s) understand what you are trying to

•

Does your e-mail message contain only makes sense

many

now

people

work

for their

initially

but

communicate?

a relevant subject line?

A good

subject line not

continue to make sense in a few months. Note that

will

use their e-mail system as a sort of database

management system

life.

•

Have you edited the e-mail message?

•

Are you sending

this

message to the appropriate recipients? Are you sending

who will be annoyed by receiving irrelevant e-mail? Are you excluding who will feel left out if they learn that you didn't send them a message?

anyone ients •

Is

the e-mail the right length? Recipients are often

e-mail. Conversely, •

Could

•

What

a recipient

is

make

sure the e-mail

is

annoyed (and

it

to

recip-

will ignore) lengthy

long enough to cover what

it

needs

to.

misunderstand your e-mail and get angry?

your emotional

state? If

you are responding angrily

to something, consider

handling the situation in person or via the telephone instead of through e-mail. •

If

you

are sending e-mail to people in another culture,

examine the message

for the

following:

- Does your e-mail message contain slang understand? In this case, jargon

on page - Could

that recipients in other cultures will not

okay, but slang

and "Native Culture" on page

13

this

is

is

not. (See "Native

Language"

15.)

e-mail message offend someone, even inadvertently, in another

culture?

-

If

English

long,

is

a

second or third language to the recipients, does your e-mail contain

complex sentences? Your message should contain

- Are you requiring

short, simple sentences.

that a recipient respond through e-mail?

atively unfamiliar with English

English to a large mailing

list.

might

feel

A

recipient

embarrassed to respond

who

is rel-

in written

Consider allowing the recipient to send an e-mail

message directly to you, and then

tactfully indicate that

you

will edit

any gram-

matical or spelling problems before transmitting the edited message to the mailing

256

E-Mail >

list.

Summary

of E-mail

SECTION 4

Editing

and Producing

Documents

Iter

A

completing the

first

draft of a

document, you

with the job. This section explores

how

are not even close to being

to edit properly

and generate

done

a profes-

sional-looking document.

257

CHAPTER

18

and the Documentation

Editing

Process

more time reviewing other

ngineefs and scientists generally spend

i

:

ments than writing lot

Editing

and

is

their

own. For

this reason,

it

pays to learn a

people's docu-

little

something

about editing and the documentation process. the art of humiliating writers critiquing

clarity.

Generally speaking, editors

falls

documentation

to

improve

its

accuracy

into two categories:

•

technical editors (often called technical reviewers)

•

literary editors

Technical editors are fellow engineers and scientists searching for technical errors, logical fallacies,

and outright

lies

mathematical mistakes.

documents of perjury

vict

technical editors are the

Good

bane of

Literary editors are experts

in

my

existence

grammar,

developmental editors

•

copy editors

Developmental editors ways

to

are writing experts

improve organization and writing

and technical writing who, fall

who work

style.

con

Good

a writer's best friend.

spelling,

are neither scientists nor engineers. Literary editors

•

technical editors live only to

save writers from publishing embarrassing documents.

into the following

at

the

macro

level.

two

typically,

categories:

They suggest

For example, a developmental editor might

suggest rearranging chapters or converting passive sentences into active voice.

Copy ter

editors work

at

the micro level.

They pore obsessively

diligently

through every

let-

Copy edibun highly

of every blasted word looking for nit picky spelling and grammatical errors.

tors are stereotypically

attractive people

bespectacled

who must

women

with hair pulled into a tight

be respected because we always get the

Editing

last

word, Rosenberg!

and the Documentation Process

259

What

Editing:

Most

Is

Really?

It

technical people believe completely in the veracity of the following formula:

effective editing

= finding mistakes

Unfortunately, the preceding formula

effective editing

The

= getting writers

editor/writer relationship

editor,

you can find error

is

is

flawed.

A more

is

as follows:

to fix mistakes

inherently difficult.

after error,

accurate formula

No one

likes to

but your findings are worthless

be

if

criticized.

As an

any of the following

are true:

know what you

•

The

writer believes that you don't

•

The

writer feels insulted by your

•

The

writer has had dealings with previous editors and has trouble distinguishing you

are talking about.

comments.

from them.

The

•

writer strongly believes that his or her

way

is

better than yours.

For the preceding reasons, the foundations of successful editing are as follows:

In

•

Building credibility so that the writer will take your

•

Sharpening your diplomatic

an

ideal world, the writer sees that

Forgive

me

—

I

and

realized that I've

on you.

Many

professionals see their writing as an extension of themselves

when anyone

criticizes

it.

virtually

Many professionals perceive editors as many professionals, editors seem

of their creative freedom. To the

good

parts."

Good editors, meanwhile,

sprung

a ridiculous

no one can divorce one's writing from one's

cliche

In

seriously.

the writing, not the writer, being evaluated.

it is

just reread the previous sentence

my experience,

comments

reduce the writer's defensiveness.

skills to

and

stumbling blocks intent

are just doing their job,

ego.

get quite defensive

—censors

on removing

which

is

to

"all

uphold truth

and improve documentation. Ultimately,

and

if

Somewhere, you" to the

260

things goes well,

all artifice is

respects the editor's improvements.

Editing

removed. The writer sees the edits

Documents become more

in a tiny, seldom-visited place in the writer's ego, the writer

editor.

and the Documentation Process >

Editing:

What

Is

It

as valuable

accurate and clearer.

Really?

whispers "thank

Technical Editing a Peer's

When

performing

on

a technical edit

a peer's

Work

work, follow the guidelines on

this page.

Provide Positive Reinforcement

You should provide plenty of

positive reinforcement in your

well- written, say so. If a section tive

even

a

few positive

is

comments.

accurate and clear, say so. You'll be

comments

A

are.

If a

amazed

paragraph at

how

is

effec-

spoonful of sugar really does make the medicine

go down. Starting off your comments with

a positive

global

comment

can make

all

the dif-

ference.

Search for Omissions

Good

technical editors search not only for technical mistakes but also for technical omis-

sions. Technical editors often focus

Avoid Vague

on what

is

present and neglect what

is

missing.

Comments

Bad technical editors provide vague comments; good technical editors provide ments. For example, the following

comment

The preceding comment only becomes

useful

is

clear

com-

worthless and rude:

when

followed by an explanation of what

is

correct; for example:

You were close— actually, the subtropical ridge

is

usually centered near latitude 32.

Suggest Replacement Text To increase the odds of a writer accepting replacement or alternate

replacement

text,

text.

a

suggestion,

good technical

For example, the following

so a hurried writer might skip over

editors suggest

comment does not

provide any

it:

This has to do with the subtropical ridge. Ask Michelle to explain.

The preceding suggestion ment has I'd

a far greater

necessitates

some time-consuming

research.

The following com-

chance of being incorporated:

suggest something

like

the following: "Tropical cyclones typically curve around the

perimeter of the subtropical ridge."

Editing

and the Documentation Process > Technical Editing a Peer's Work

261

Technical Editing a Superior's

If

you

are editing the

low the guidelines on

work of a superior

(either a

Work

manager or

a

more senior

scientist), fol-

this page.

Provide Thanks Provide

a

quick preface to your

edits,

thanking your superior for the opportunity to

preferably without sounding too obsequious. For example, the following

It

is

a

thrill

However,

I

a

it

lot

edit,

just too gushy:

work with someone as famous as you.

comment such

learned a

Make

to

is

about

clear that

as the following

artificial insulin

is

appropriate:

research from reading this paper.

you would be honored

to review

subsequent drafts of the document.

Phrase Edits as Suggestions Phrase your edits as suggestions whenever possible. Obviously, a misspelled word spelled

word and should be handled

handle more subjective matters with

as a straightforward correction. care.

is

a mis-

However, you should

For example, the following

is

far

too direct for

a superior:

Eliminate the opening sentence.

Rephrasing an imperative order as a question or suggestion for example, consider the following

How

about

if

will serve

your career

you omit the opening sentence and use that strong second sentence as

your opening?

Ill262

Editing

better;

improvement:

and the Documentation Process > Technical Editing a Superior's Work

Copyediting a Colleague's Document

A copy editor times, you

wonderful resource that many organizations simply cannot afford. Some-

a

is

must

act as the

Sometimes you must

de facto copy editor on a project because no one

take that critical last look at a

mistakes before outsiders do.

If

you find yourself

document

to catch

else

is

available.

any embarrassing

in this situation, here are a

few sugges-

tions for performing a quick copy edit:

•

View the

same medium

draft in the

as the target

document

target audience will read the

in

audience

PDF, review

a

will.

PDF

For example,

if

the

version of the draft,

not a paper version. •

Check

the table of contents.

Does

it

include

all

the chapters and top-level section

headers? •

Check

all

and footers

the headers

in the

displayed? Are any pages missing?

•

numbered page? Do

the page

numbering mistakes

are

contents to Chapter

1.)

book. Are they consistent? Are page numbers

If this is a

book, do

numbers sequence

common,

all

chapters start on an odd-

correctly? (Don't laugh

particularly in the transition

Get access to the word-processor sources for the document. Run

them.

grammar-checker

If a

context. For example,

if a

is

available,

run

it.

— page

from the

table of

a spell-checker

on

Most spell-checkers don't check

for

writer used there instead of their, most spell-checkers won't

report a mistake. •

Check

tables

and

match up with tions in the

Figure •

1

wrong

contain captions?

all

Do

all titles

and captions

place?)

Do

all

tables

and

figures have a numerical label, such as

1-2 or Table 7-1?

Verify that

If

they

corresponding tables and figures? (In other words, are any cap-

you placed trademarks or registered trademarks

your corporate attorney, •

Do

figures.

their

if

you only have enough time

section or chapter that will

correctly.

Consult with

necessary. to review a tiny section of the

draw the most

document, evaluate the

readers.

Spreading the Wealth

Suppose

a writer asks 10 technical editors to review a

probability, only

one or two

editors have limited time

of

them

will

it

300-page document.

past the

first

In all

50 pages. Technical

and limited attention spans. To improve coverage, the wise

writer assigns different sections of the

Editing

make

book

to different technical editors.

and the Documentation Process > Copyediting a Colleague's Document

263

Own Document

Copyediting Your

Foxes should never guard the chicken coop, inventors should never act as their

own

assurance department, and writers should never edit their else

is

uation;

you

are simply too familiar with your

will skip

One

own best editor. This is a suboptimal sitown work to do a good editing job, so you

over mistakes that would have been obvious to another reader.

of the best tricks for editing your

own work

you find missing words and awkward sentences.

on

quality

you must become your

no one

available,

own

work. Nevertheless, when

sentences.

(When you

start to

is It

to read

it

aloud. This technique helps

also does a great job of catching run-

run low on oxygen, you've found

a

run-on.)

Reading aloud generally won't help you find spelling mistakes, but a spell-checker certainly will.

Another technique

—

by

is

view

it.

—one

that

sounds ludicrous but that some professional editors swear

to "read" the text backwards. Actually,

The theory

through familiar

is

that,

text.

when

you don't

reading forwards, your

really read the text as

mind

coasts rapidly

much

and

By viewing the same passage backwards, you suddenly

see

as

you

carelessly it

in a dif-

ferent way. Obviously, this technique isn't for everybody.

You

will generally find

more

errors in passages that

you recently wrote. An old saw draft in a

—one

drawer and forgetting about

that has it

you wrote

some merit

—

a

while ago than in passages

suggests throwing your

for a while. If you are writing a lengthy

consider putting yourself on a delayed editing schedule, where you edit a chapter after you've written

are

emergency stop-gap measures. Good writing,

like

neering, ultimately requires input and feedback from multiple parties.

Ill Editing

six

weeks

it.

The preceding techniques

264

first

document,

and the Documentation Process > Copyediting Your Own Document

good engi-

Media Some

engineering teams edit paper copies of documents. Other teams edit online.

For paper

ments

for Technical Editing

edits, editors take

directly

on

and incorporates the the editors' original

approach are

revisions.

The

comments

On

writer eventually scoops

the second

It

•

Many

•

If

so that they can verify changes.

the

professional writers prefer this because

document being reviewed

In recent years,

document

document)

marked-up copies

The advantages of this

many teams

will

Most

it

gives

them more

be delivered to readers

in

reviewers'

have switched to online editing. The technology for online

marks up

a separate

copy of the source

comments). The advantages of online editing

technical reviewers can type

keyboard lengthier illegible

is

much

faster

useful.

can see and comare as follows:

than they can handwrite. Since the

mightier than the pen, reviewers tend to supply

and more

control.

hard copy, then

to rather elaborate (using collaboration software, reviewers

ment on other

comments

that are

Furthermore, writers never run into problems reading

handwriting.

Depending on

the technology, writers can

accept the change request, and

it

will

sometimes simply indicate

that they

be automatically implemented.

Online editing saves paper.

•

Most high-end word processors provide any

the

as readers will.

editing ranges from fairly simple (each reviewer

•

all

as follows:

reviewers see the

•

up

round of editing, the writer should return

simple to implement.

•

is

out their trusty red pen (nicknamed "Satan") and write com-

the hard copy.

text that has

a

change-bar feature, which automatically

changed since the previous version. Whether editing hard or

the change-bar feature helps focus editors' energy

Editing

on the second

flags

soft copy,

pass.

and the Documentation Process > Media

for Technical Editing

265

Bug-Tracking Systems

Most engineering organizations use

Many efits

a

bug-tracking system to monitor defects in a product.

organizations also use these systems to monitor defects in documentation. The ben-

of such a system are pretty

documentation •

Unlike

•

A

defects.

much

the same, whether you are tracking engineering or

Namely, the key advantages are as follows:

human memory,

bug-tracking system

a

lets

bug-tracking system won't forget bugs.

managers

prioritize

bugs to help focus

effort

on

the

most

serious defects. •

A

bug-tracking system records fixed bugs to prevent duplication of

The disadvantage of a bug-tracking system it

a

sometimes takes person

tem

if it

who

finds a misspelled

tuous, but the goal

is

new bug

word might avoid reporting

takes five precious minutes to

easier to e-mail the writer

monitoring documentation defects

for

long time to open a

a disproportionately

open

a

effort.

new bug

it

through

report. After

a

and correct

as

many bugs

as possible,

that

bug-tracking sys-

all, it is

oh-so-much-

about the mistake. I'm not saying that the easy way out

to detect

is

report. For example,

is

vir-

and the bug-tracking

system might hinder that goal.

I

recommend

using a bug-tracking system to report and monitor documentation bugs after

the initial release of the

document. Prior

copy or online editing techniques noted

to the initial release, in this

I

recommend using

the hard-

chunk.

QUANTUM LEAP To reduce the number of documentation defects

in

early drafts (no matter

are reported), always put your best effort out for review.

and reread your document their reviewing

stantial technical issues. To

hanging

266

Editing

prior to submitting

energy on easy

stuff

it.

Too

In

how they

other words, spell-check

often, technical editors focus

(such as misspelled words) rather than on sub-

keep technical editors focused, give them less low-

fruit to harvest.

and the Documentation Process > Bug-Tracking Systems

A Process Editing project

is

for Editing

essentially a quality assurance process for

team approaches documentation

and balances. The process

documentation. Therefore, the wise

as an engineering process requiring a set of checks

documentation should

for creating

ideally contain the following

well-defined phases:

1.

Writer creates documentation specifications.

2.

Writer generates Draft

1.

3.

Literary editor performs a literary edit

4.

Writer incorporates literary edit

5.

Team performs

on Draft

comments and

on Draft

a technical edit

1.

generates Draft

comments and

6.

Writer incorporates technical edit

7.

Team performs

8.

Writer incorporates technical edit

comments and

9.

Copy

on Draft

10.

on Draft

a technical edit

editor performs a copy edit

Writer incorporates copy edit

The preceding assumes nately, the perfect

a perfect

world

filled

3.

generates Draft

4.

4.

generates final document.

with plenty of time and resources. Unfortu-

as attainable as a perfect

is

teams skip plenty of the preceding steps

Enough Time

generates Draft

3.

comments and

engineering world

to allow the writer

sense suggests that the quality

reviewers

more

time. However,

common

for writing.

of edits

and reviews increases as you give

sense does not apply here. An old

managerial adage states, "Work contracts or expands to experience suggests that this adage

days to edit a 150-page document

is

will

fill

My

the time allotted."

dead-on. For example, reviewers allotted three

do

just as

good a job as reviewers

three weeks. Naturally, there are limits— you can't expect in

vacuum. Many engineering

more time

to Review

Common

page book

2.

2.

someone

allotted

to review a

500-

a day.

Technical reviewers often generate conflicting comments. reviewers together over the

phone or

When

this

happens, get

all

face-to-face. Don't let reviewers debate this sort of

thing in e-mail as the discussion often turns contentious and unproductive. People's voices are far

more

polite than their e-mail messages.

Editing

and the Documentation Process > A Process

for Editing

267

)

Beta Tests for Documentation

In a beta test, real-world customers play with an almost-finished product

inventors what they like and what they don't.

improve

Good

Good

and

tell

the

engineers use this valuable input to

their products.

engineering organizations also beta-test documentation. Unfortunately, most engi-

neering organizations don't beta-test documentation optimally and end up with worthless

comments such

as,

"The documentation was

ments on documentation, you have If

the documentation

to

distributed in

is

go

HTML

tation feedback button onto every page.

with

lots

the total

comments

this

number of Best-testers

at the

Assure beta-testers that

form

form extremely simple; don't weigh

is

title.

it

In fact, the best

small, try to identify each individual test,

who

will read

contact beta-testers and deter-

all

beginning, you'll be more likely to get good feedback

(good and bad)

their feedback

is

of communication open. Get feedback while an idea so an instant

medium such

Don't rely on surveys

at

the

as

end of a

IM

is

just

is

as a 4

on

a scale of

your organization

insists

fresh in the

1

to 7,

how

mind of a

beta-

about perfect.

beta-test to get

on

you

later.

quite helpful. Then, keep the

documentation feedback.

survey will typically garner only general comments. For example,

tation? If

documen-

are responsive to further questions about the documentation. (If

can get them to agree

documentation

com-

for suggestions, period.

mine whether they

tester,

a

a beta-tester presses this button, a

the beta documentation. At the beginning of the beta

lines

beta-test

aggressively.

of extraneous information such as the beta-tester's

form simply asks If

you want worthwhile

If

format or as online help, build

When

should pop up asking for suggestions. Keep

down

okay."

after those

exactly

if a

A

closing

respondent rates your

would you change your documen-

a closing survey, try to get

respondents to identify

missing topics. If

your organization

is

financially blessed, offer financial carrots to beta-testers

who

pro-

vide significant feedback.

Determining Where to Spend Documentation Resources

When communicating

with beta-testers,

make

sure you determine which documents

they read most often. Then, after beta-testing finishes, focus your documentation resources on improving these documents. Fish where the fish are biting.

1 268

Editing and the

Documentation Process > Beta Tests

for

Documentation

Summary

of Editing

and the Documentation

Process

When •

performing any

Remember

that

sort

of edit, follow

this general advice:

you are editing the work of

a fellow

human and

most humans

that

are sensitive to criticism. •

Find something to praise about the document, even ally

When

something good about the document,

performing

a technical edit (technical

if it's really

bad;

if

there

is

actu-

well, all the better.

review)

on

a

document, focus on the

following:

•

Forget that you are you; instead, imagine that you are for this

•

document. Determine what

Perform any documented steps installation

that person

you

would. For example,

a software install the

—

doing exactly what

treat the text literally,

it

to do.

Determine what

•

Provide clear criticism so that the writer knows

•

audience

know. if this is

just as a user

•

When

in the target

to

manual, find suitable hardware and use the documentation to

software. Don't read between the lines tells

someone

would need

performing

is

missing from the manual.

a literary edit

or

a

copy

edit

on

a

how

to fix the

problem.

document, focus on the following:

Follow the advice in Section 2 of this book, which details best technical-writing practices.

Pass along this advice (diplomatically) to the writer. For example, identify pas-

sive-voice sentences that should be

changed

to active voice.

•

Review captions to make sure that they are informative and accurate.

•

Search for context problems that spell-checkers would miss.

•

Identify passages that are unclear.

•

Prior to editing, jot

make

Editing

down

a

sure that you can find

few topics that you expect to find in the book. Then, all

of them in the index and in the table of contents.

and the Documentation Process > Summary

of Editing

and the Doc. Process

269

I

CHAPTER

19

Fonts and Typography

Although favorite in

New

it is

difficult to pick the best tourist attraction in

diner

jersey, a

is

who end up

selecting

Jersey,

who

my personal

don't vacation

a friendly, inexpensive restaurant that features

length menus, often with hundreds of entries. Sadly, the massive

patrons

New

never-ending supply of diners. For those of you

is its

something more dorky than

book-

menus overwhelm many

fulfilling."

Every modern computer system provides dozens, even hundreds, of fonts. Most computer users ignore this cornucopia and stick with the safe defaults chosen by their

ing software. This leaven a casual

is

a real pity. After

all,

document. Picking the

fonts can give gravity to a serious

right fonts can

professional, just as picking poorly can detract

On

the Other Hand,

make your documents look more

Mashed Potatoes Are Comforting

should set a serious technical document just

because

it

in

I

don't want to suggest that you

a novelty font such as Papyrus or Park

would give your document a

distinct look. Novelty fonts can

punch up

a birthday card or an advertisement, but they have no place in the kinds of

scientific

documents

that you are writing.

Until a few decades ago, a chapter

on

fonts

would not have appeared

mortals. In the old days, engineers and scientists wrote the words and to trained printing professionals. a

process-

from your message.

Fonts don't have to be exotic to be interesting.

Avenue

word

document or

few mouse

clicks.

in a

book

left all

for

mere

font decisions

Nowadays, though, anyone can conjure font changes with

This chapter helps you click wisely.

1.

Burgers and

2.

Latkes with apple sauce. Try the cheese blintzes, too.

fries.

1Fonts and Typography

271

and Sans-Serif Fonts

Serif

If

you look very

closely at the

words

in this sentence, you'll see tiny

notches popping out from the ends of most of the ous, I've

blown up

a lowercase

p

letters. Just to

horizontal and vertical

make

it

a

little

more obvi-

in Figure 19-1.

serif

* serif

serif

FIGURE

19-1

This lowercase

p

contains three

Notice the tiny horizontal lines left.

These tiny

at the

lines are called serifs.

serifs.

base of the

Some

p and

the tiny

fonts have them,

which most of the characters have

serifs are called

which none of the characters have

serifs,

little

hook

and some

in the

upper

don't. Fonts in

(not surprisingly) serif fonts. Fonts in

such as the character shown in Figure 19-2, are

called sans-serif fonts.

P FIGURE 19-2

This lowercase

p

contains no

serifs.

Table 19-1 summarizes three popular serif fonts. thickness of the lines

272

The Weight column

and curves constituting each

refers to the relative

character. For example, printing the

Fonts and Typography > Serif and Sans-Serif Fonts

let-

ter o in a

heavy-weight font expends more ink than printing

of these fonts provide

TABLE

19-1

a boldface version that

A Few Popular

in a light-weight font.

it

Many

exceptionally heavy.

Serif Fonts

Example

Garamond

is

The quick brown

fox

Weight

Comment

Light

This font suggests elegance and preci sion.

It

features ornate serifs (look

some

closely at the T), which strike

readers as old-fashioned. Palatino-

Linotype

Medium

The quick brown

This

is

a bit

good choice

wider than

so text

Times New

a

for technical

documents. Characters

fox

The quick brown

fox.

Heavy

Roman

in

in

this font are

the other two fonts,

consumes more space.

This font also

makes

a

good choice

for

technical documents, but because of its

ubiquity,

Roman do

documents

Times New

in

not stand out.

Table 19-2 summarizes three popular sans-serif fonts.

TABLE 19-2

A Few Popular Sans- Serif Fonts

Name

Example

Anal

The quick brown

fox

Weight

Comment

Medium

Microsoft developed this font for online use, so ever,

Benton-

The quick brown

fox

Light

The quick brown

Heavy

fox

it

is

looks excellent online; how-

not great for hard copy.

This font looks very sharp

but a

Gothic

Verdana

it

little

smudgy

distinctive look. Notice

table.

font

systems use Arial and Times

New Roman

hard copy

This font gives hard-copy documents a

relative to the other

Many

in

online.

If

space

is

how wide

two fonts

at a

it

is

in this

premium,

this

would not be a good choice.

as the default fonts, so users with typo-

graphic inertia often just go with these fonts. Both fonts are sturdy choices. However, since they are ubiquitous, documents that use them do not stand out.

document with

a distinctive

If

you want

to

imbue

a

look or brand, then you must choose nondetault fonts.

Fonts and Typography > Serif and Sans-Serif Fonts

273

Fixed-Width versus Variable-Width Fonts

All the fonts

examined so

far

—whether

—have been variable-width

serif or sans serif

In a variable-width font, each character occupies only the horizontal space

following example, notice

how B and

it

fonts.

needs. In the

snuggle up tightly:

i

BiBi

Every character in a fixed-width font (also called a monospace font), whether brawny or svelte,

consumes exactly the same amount of horizontal

acters

end up with

ple, notice

a lot

how much

space. Thus, naturally skinny char-

of white space around them. For example, in the following exam-

blank space

is

between each pair of letters:

BiBi

Fixed-width fonts use horizontal space

less efficiently

than variable-width fonts. Table 19-3

describes two popular fixed-width fonts.

TABLE 19-3 Font

Two Popular Fixed-Width Fonts

Name

Courier

New

Example

Comments

The quick brown fox

This

is

the classic, universally available

fixed-width font. Similar fonts include Courier.

Lucida

The quick brown

Notice that Lucida Console

Console

fox.

Courier New.

Many readers

is

wider than

find Lucida

Console more legible than Courier New; however, Lucida Console sally available

Fixed-width fonts are generally

less

is

not as univer-

as Courier New.

readable than variable-width fonts. In addition, large

blocks of text in fixed-width fonts don't look good. Nevertheless, you should use

them

to

display the following:

•

programming source code or command

•

mathematical or

many •

scientific

lines

equations (although you probably need a special font for

equations)

values that

must

line up,

such as

in a

spreadsheet or database

m 274

Fonts and Typography > Fixed-Width versus Variable-Width Fonts

a

and Sans-Serif

Serif

When

in

Hard Copy

producing hard-copy documentation,

a

simple formula for typographic success

is

as follows:

•

Use

a serif font for all

body

text,

which includes the following:

- paragraphs

•

-

lists

-

table cells

Use

a sans-serif font for all

- chapter

titles

header

text,

which includes the following:

and section headers

- table headers

-

table

-

figure callouts

and

figure captions

- page headers and footers, plus page numbers •

Use

a

fixed-width font for

all

special elements,

which include the following:

- equations

- software commands or code In other words, a

document should

serif font, a sans-serif font,

for If

all

body

you were

text,

and

Verdana for

typically contain a

grand

total

a fixed-width font. For example,

all

header

to use only a single font

text,

and Lucida Console

of only three fonts

for

all

special elements.

throughout the document, section headers and table

captions would tend to hide. Following the three-font formula makes to find

—

you might use Palatino

it

easier for readers

what they are seeking.

Serifs Are

Many

Sweet Noise on Paper

centuries ago, typographers discovered that serif fonts were

than sans-serif fonts. This

is

more readable

rather astonishing because serifs are essentially

noise-

extraneous particles strewn over a clean surface. (Can you think of any other instance

In

which adding noise to a system makes

Although sans-serif fonts look cleaner than favor of serif fonts

is

it

more comprehensible?)

serif fonts,

the readability evidence

overwhelming. Nearly every hard-copy novel

is

set

in

in

a serif

font.

Fonts and Typography > Serif and Sans-Serif

in

Hard Copy

275

Serif

When

and Sans-Serif

Copy

Soft

producing soft-copy documents, you should

rely entirely

on

sans-serif fonts.

Chords Online

Serifs Strike Sour In

in

hard-copy documents,

serif fonts are

more

readable. However, in soft-copy

documents, sans-serif fonts are more readable. The reason has resolution of the different media. Most hard-copy published

to do with the documents are printed

at

1,200 dots per inch. However, even the best monitors can render soft-copy

documents at only 125 dots per inch or so. At such a low smudged, but sans-serif fonts still look clean and sharp.

Most people choose one of

the following

two

resolution, serif fonts look

strategies for using sans-serif fonts in soft-

copy documents: •

Apply

•

Apply two

a single sans-serif font

throughout the document.

different sans-serif fonts; for example, use Arial for

body

text

and Verdana

for headers.

Even

if

you choose the

latter strategy,

as font size, indentation,

and color)

you must

sans-serif fonts generally look rather similar;

from Verdana. Using

still

rely

a different color

is

on additional

body

to differentiate

text

most readers cannot

much more obvious

characteristics (such

from header

text.

Different

easily differentiate Arial

than using a different sans-

serif font.

Arial

is

a very

popular choice right

now

for online

machines running Microsoft Windows. That

is

documentation, particularly on

because Arial was designed specifically for

soft-copy documents. (Most fonts were designed for hard-copy documents.)

Mixed Media

Sometimes you must provide the same document

in

such cases, you should determine which medium

is

accordingly.

When

both hard copy and soft more popular and apply

hard copy and soft copy are equally popular,

rules for hard-copy

documents. One other

possibility

is

usually use the

to generate

two different

versions from the

same

source. The only disadvantage to doing so

numbering might

differ

between the two versions, which can cause confusion.

12 276

I

copy. fonts

Fonts and Typography > Serif and Sans-Serif

in

Soft

Copy

is

that page

In

Font Height

Font height

is

measured

in a peculiar unit called a point,

where

points = 1 inch

72

Given the preceding definition, you might expect a 36-point character to be exactly 0.5 inches

tall.

You

silly

inches. However, j)

logician, you! In fact, every 36-point character

measuring from the bottom of the

far shorter

is

font's lowest letters (for

to the top of the font's tallest letters (for example,

Z or /)

does yield

than 0.5

example, £ or

a height

of exactly

0.5 inch. See Figure 19-3.

WJ. FIGURE 19-3

A 36-point

5 inches

font

is

0.5 inches from the lowest point to the highest.

Best Font Sizes for Hard Copy

The following •

Set

all

The

are a few general guidelines for setting font sizes in hard-copy

body components (paragraphs,

size

example, don't •

lists,

and table

cells) to

you pick should be somewhere between 10 and set

paragraphs to 10 points and bulleted

Sans-serif fonts look a

little

reason, set the following

the

documents:

same

font size.

11 points, inclusive. For lists

bigger than serif fonts of the

to 11 points.

same point

size.

For

this

components one point smaller than body components:

- table headers

-

table

-

figure callouts

and

For example,

figure captions

if

you

set

your body components to an

1

1-point font, set your table

headers to a 10-point font. •

Leave big deltas between different section header of

at least

three points (four points

header and

a

is

better)

levels.

I

like to leave a difference

between the font

sizes

of a

first-level

second-level header. For example, readers can easily distinguish

Fonts and Typography > Font Height

277

between an 18-point

header and

first-level

and

difference between an 18-point

a

a 14-point second-level header,

16-point font

is

much

but the

harder to distinguish.

Larger Fonts Appeal to Older Readers

One

of the central

theorems

in

communication

technical

is

to

be

clear. For this

when

reason, good technical communicators consider the age of their readers

making

font decisions.

When

writing for the over-40 set, never pick a

smaller than 10 points. Older readers greatly prefer an 11-point body.

your readers can't click a

menu

to

make

text bigger in a

body font

Remember-

hard-copy book.

Best Font Sizes for Soft Copy

PDF and HTML

are the

two most popular formats

for online

documentation distribution.

When creating PDF documents, absolute font sizes are not important since readers can easily

change the

fonts sizes are

effective font sizes still

through

important, so the

a

simple

menu

size guidelines for

selection. Nevertheless, relative

hard copy are relevant for

PDF doc-

uments.

When

creating

HTML

documents, you must choose between one of the following

strate-

gies for setting font sizes:

•

Set font sizes explicitly

•

Do

The

first

not

through

HTML tags or through cascading style sheets

set font sizes; instead, let users set

strategy

—

—

1

1

-point Arial. However, this control

you can

is

tell

somewhat

the browser to render illusory because

The second

strategy

—

letting users pick font sizes

—

is

on

a

is

much

Hi 278

Fonts and Typography > Font Height

easier to

offers the

paragraphs

1

1

-point Arial

1600 x 1200 screen.

generally preferable for technical

documents. This strategy permits users the luxury of adjusting the font needs. In addition, this strategy

all

you cannot control

the screen resolution at which readers will view the document. For example,

looks sharp on an 800 x 600 screen but becomes intolerably tiny

(CSS).

controls.

setting font sizes (and other font characteristics) explicitly

greatest control. For example, with a CSS, in

them through browser

implement than

a

to

CSS.

meet

their eyes'

and Boldface

Italics

Most

fonts provide

ticular a

italic

and boldface (or

word, so when would you

just bold) variants.

italicize

Both draw attention

few guidelines. Note that these are only guidelines, not hard-and-fast

guidelines you choose, apply

For example,

terms with

if

them

to a par-

and when would you bold? This page provides

you introduce new terms with boldface

rules.

Whatever

document or documentation

consistently within a in

set.

one chapter, don't introduce new

another chapter.

italics in

Boldface Boldface stands out

more than

tion to a

word or phrase, put

way.

page contains too

If a

italics.

it

much

•

•

in the

you

really

want

—

to

draw

a little

readers' atten-

bold goes

when

a

long

many

they aren't. (Large fonts often look bold.)

I

boldface for the following passages:

when introducing new terms

Polyprotic acids

if

Don't overuse bold

boldface, the impact of boldface fades. Note that

headers appear to be in boldface even

recommend using

Therefore,

in boldface.

in a

paragraph, as in the following passage:

contain multiple acid hydrogen

in

each molecule.

portion of a command-line dialog that a user enters verbatim; for example,

notice that the user literally enters prime

and 23

in the following passage:

prime

$

Enter an 23

integer:

23

prime.

is

Italics I

recommend

using

of a book,

•

the

•

a foreign

•

in

title

italics for

word

the following:

article,

or other copyrighted source

or phrase not found in an English dictionary

word or passage that the user must command, the user must enter an integer (not

software documentation, any nonverbatim

enter; for example, in the following

the

literal

word

integer):

dexprime integer

Note that

italics

rather than

show up badly

online, so

many Web

writers use boldface for emphasis

italics.

II::.

Fonts and Fypography >

Italics

and Boldface

279

Consistency and Convention

Whatever fonts you choose, apply them Palatino for

all

body

text,

you should also apply boldface,

How do

you make sure

consistently. For example,

then stick with

that

italics,

it

if

you

with

start off

throughout the entire document. In addition,

and fixed-width fonts

consistently.

you apply fonts consistently? The key

is

to

work with

a strict

word-processing template" rather than blindly pressing the Ital ic or Boldface button. For example,

a

good word-processing template should define components with names such

as

the following:

•

Emphasize

•

NewTerm

When

a writer needs to

emphasize

a passage, instead of trying to

italicize,

way,

emphasized passages end up

all

One of the benefits of the ple,

remember whether

the writer simply "tags" the text with the Emphasize

bold or

in the

same

preceding approach

suppose the Emphasize component

is

is

component.

font.

that

defined as

it

simplifies global changes. For

italic. If a

new

editor arrives

decides that the corporate standard for emphasized passages should be boldface, ple matter to

implement

this

change

just

to

In this

exam-

and

it is

a sim-

by redefining the Emphasize component.

Font Conventions

Many manuals

contain a "Font Conventions" section identifying the purpose or usage

each font

the manual. For example, such a section might indicate that 10-point

of

in

Courier bold represents text that the user must enter verbatim.

On one hand,

"Font Conventions" sections remove potential ambiguities.

other hand,

a

if

manual requires such a

section, then the fonts

in

that

On

the

manual were

probably not clear enough.

3.

This

is

often called an

SGML approach. SGML, or Standard General Markup

HTML.

I 280

Fonts and Typography > Consistency and Convention

Language,

is

a superset

of

True-Type versus PostScript Fonts

Two

different font technologies

fonts

•

•

on

a

Windows PC

True-Type

fonts,

dominate the personal computer world. Almost

all

the

or Macintosh rely on one of the following standards:

which have the .TTF

PostScript (also called PostScript Type

file

1

extension on Windows-based PCs

or just Type

1) fonts,

which have the .PFM

and .PFB extensions on Windows-based PCs

Which category

is

better?

True-Type fonts get more use because Windows PCs come

fully

stocked with them. However, most professional graphic artists prefer the superior quality

of PostScript fonts. PostScript fonts

come

in

tandem

files,

with one

holding the screen version of the font and the other (the .PFB sion. In

the

A

some

same

single

cases, font creators

produce both

a

file)

True-Type and

file

(the

.PFM

file)

holding the printer vera PostScript version

of

font.

document should always use

True-Type and PostScript fonts

a single font technology. In

in a single

other words, never mix

document. Mixing font technologies often

causes printing problems.

Fonts and Typography > True-Type versus PostScript Fonts

281

Summary

and Typography

of Fonts

Ask yourself the following questions about the font choices •

What -

If

is

the output

the output

medium

medium

for this

in

your document:

document?

is

hard copy, have you used serif fonts for body and sans-

is

a

serif fonts for headers?

-

If

the output

medium

computer

screen, have

you used sans-serif fonts

for

everything? •

Are the fonts big enough

to be legible?

- Will older readers have trouble reading -

If this is

an

HTML document, Can

to see these fonts?

-

•

will readers

on high-resolution monitors be

the

body

text set in 10-

body

text?

If this is a

hard-copy document,

is

- Do you use

italics

first-,

1

1

-point type? Are

Are the fonts obtrusive?

consistently?

fonts for headers

and

Fonts, like journalists,

footers?

should

tell

attention to themselves.

Fonts and Typography >

set)?

second-, and third-level headers change?

and boldface

- Do you use consistent

282

or

Are fonts used consistently throughout the document (and document the settings for

able

readers change the size of fonts?

the headers noticeably larger than the

- Do

•

these fonts?

Summary

of Fonts

and Typography

the story without calling

CHAPTER 20

Punctuation

Please

forgive this

grammatical intrusion, but many people have trouble using the

following punctuation marks correctly:

•

commas

•

dashes and hyphens

•

semicolons

•

periods

•

colons

•

quotation marks

This appendix does not provide a comprehensive look

summarizes

most

their

nuance, see a

style

common

manual, such

at these

uses within technical prose. as the

punctuation marks; If

it

only

you want to learn every

Chicago Manual of Style.

Musical Punctuation If

words are notes, then punctuation marks are

think of punctuation

If

comma

•

A

•

A dash

•

A semicolon

•

A period

is

sheet music

is

in

rests. Musically

speaking, you might

the following way:

a quarter-note rest.

a half-note rest.

is

is

a three-quarter note rest.

a full-note rest.

isn't

your thing, don't worry— all

will

become

clearer

in

the next few

pages.

Punctuation

283

Commas English

about anywhere.

whether

tain

and there

a rather flexible language,

is

comma just your voice

to use a

A comma

comma, just

rests briefly.

atoms are

is

one

of

the

little

to stop

you from placing

read the sentence out loud and place a

when reading the word life:

For example,

voice should pause briefly just after

Although carbon

very

is

a

signals a short pause or division. If you are uncer-

elements of

critical

comma anywhere

the following sentence out loud, your

life,

a tiny percentage of carbon

naturally radioactive.

Technical prose often contains conditional sentences. In a conditional sentence, use a

comma

from the consequence. For example, the following con-

to separate the condition

ditional sentence contains an explicit

If

the pressure drops by

iff

and

more than 10

mb

then:

in

an hour, then a severe storm

is

on the

way.

The previous sentence contains an

word

then

is

explicit then,

implied. In such sentences, the

but in

many

comma is critical

conditional sentences, the

to helping the reader identify

the implied then. For example, in the following example, notice the

If

the pressure drops by

As noted

in

Chapter

Nevertheless, after ple,

if

7, technical

comma

Three types

Good

mb

list

is

an hour, a severe storm

list

284

Punctuation >

Commas

embedded

lists.

commas

element (oranges) and the second element (lemons):

built for speed;

1

to

on the way.

with more than two items, place

lemons, and limes.

commas

act as speed

sentences within technical prose should rarely contain

containing more than two

lists

is

after hour:

except the final element. For example, in the following exam-

after the first

of citrus fruits are oranges,

technical prose

in

communicators prefer bulleted

you do create an embedded

each element in the

note the

more than 10

comma

commas

bumps. As

a rule of

thumb,

more than two commas. Sentences

are ripe for editing.

Dashes and Hyphens Dashes come

in the following

•

em

•

en dashes

dashes

The en dash

common

is

(

—

(-),

),

two

which are

which are

flavors:

as

as

wide

wide

the grammatical fifth Beatle

use in technical prose

is

in

"M"

as the letter

as the letter

"N"

in a

given font

in a given font

— most people

just

want

it

to

go away.

only

Its

numerical spans, such as the following:

The hybrid engine increases gas mileage 30-50%.

Like

commas, em dashes

are signals for the reader to pause. Readers pause longer for

dashes than for commas. Em-dashes often travel in pairs. The text between a pair of dashes often provides

Iodine

is

a

quick definition, as in the following example:

halogen— a nonmetal with

a

em em

a single electron to

donate— and a common

allergen.

Hyphens A hyphen

is

a very short

dash

(-),

even narrower than the en-dash.

matically supply hyphens to split multisyllabic explicitly

the

words

at the

end of

Word

processors auto-

a physical line.

You

supply hyphens to string together a group of unsplittable words. For example,

hyphens

in the following

example unite four words into one compound noun:

Crank the handle as you would a jack-in-the-box.

The hyphens

in the

preceding example are essentially the opposite of commas;

commas

cause readers to slow down, but hyphens cause readers to speed up. In the preceding example, the

also use

the

reader mentally runs the hyphenated jack-in-the-box together as one word. You

hyphens

hyphens

to join a

in the

multiword adjective preceding a noun; for example, consider

following example:

The corpus callosum helps convert short-term memories

Be careful tive,

—do not use

a

into

long-term memories.

hyphen unless the modified noun follows the multiword

for example, the following example correctly contains no hyphens because the

memories does not follow either of the multiword

adjec-

noun

adjectives:

The corpus callosum helps convert memories from short term

to long term.

Ill

Punctuation > Dashes and Hyphens

a:'

285

Semicolons

Use

a

semicolon to connect two closely

complete sentences.

related,

A

semicolon and

a

period are essentially interchangeable; however, the semicolon suggests the marriage of a perfectly

matched couple, almost

as if the writer couldn't bear to separate the

two thoughts

with something as harsh as a period. In the following sentence, notice that the two sentences are so closely related that the writer could have reversed their order:

Hydrogen

is

the only element without a neutron; each hydrogen

atom contains only a

proton and an electron.

Good a

words such

writers often place transition

semicolon.

Remember

to place a

comma

as

however and therefore immediately

immediately

after the transition

after

word. For

example, consider the following:

A

stable helium nucleus contains two protons

You may place

comma A

a transition

word

and two neutrons; however, several

more than two neutrons.

unstable helium isotopes contain

in the

middle of a sentence. In such instances, put

a

before and after the transition word, as in the following example:

stable helium nucleus contains two protons and two neutrons; several unstable

helium isotopes, however, contain more than two neutrons.

You may

place multiword transition phrases (such as on the other

immediately following a semicolon, as

On one hand,

hand or for example)

example:

Java enables truly portable programs; on the other hand, Java

programs often run

Never place

in the following

slowly.

a conjunction (such as

and or

but) after a semicolon; for example, the follow-

ing grammatically improper sentence requires a

Assembly language programs run

comma

instead of a semicolon:

quickly; but they are difficult to code.

Occasional use of semicolons helps your writing look more professional. Overuse of semicolons tends to look a

little

,

286

Punctuation > Semicolons

sophomoric.

Periods

As you know, you place

a

period

at the

end of most sentences. However, the humble period

also serves a few other uses in technical prose,

which

this

page describes.

Parentheses provide a splendid opportunity to misuse periods.

If

you place

a full sentence

within a pair of parentheses, then place the period just inside the closing parenthesis, as in the following example:

Hurricanes have sustained winds of at least 65 knots.

(In

the Pacific Ocean,

hurricanes are called typhoons.)

If

you

insert a phrase (not a

complete sentence) within

a pair

of parentheses, then do not

place a period within the parentheses. For example, notice that the period appears after the closing parenthesis in the following example:

Hurricanes have sustained winds of at least 65 knots (74 miles per hour).

You place

a

period after an abbreviation but not after an acronym, as in the following

examples:

Dr.

(abbreviation— ends with a period)

DBMS (acronym— does

not end with a period)

Exclamation Points In

recent decades, editors and pundits have

that writers literati is

who dare use

it

are

now

vilified

that exclamation points are a

cheap

book),

I'd

is

recommend

a capital

crime (hey,

at.

much

The feeling among the

trick to infuse excitement. Real writers,

they say, build excitement through words. While

exclamation points

the exclamation point so

generally sneered

I've

I

don't believe that inserting

put several exclamation points

in this

using them sparingly.

Punctuation > Periods

287

Colons

Within technical prose, use a colon to introduce

a

list,

table,

or figure that will immediately

follow. For example, the following passage correctly uses a colon to introduce a bulleted list:

Water has the following properties:

If

the

an excellent solvent.

•

It

is

•

It

becomes

list,

table,

less

dense below 4°C.

or figure does not immediately follow

its

introduction, then terminate the

introductory sentence with a period rather than a colon. For example, in the following passage, notice that the introduction occurs a

few sentences prior to the

Water has the following properties. Note that water these

critical properties.

It

is

•

It

becomes

However,

it is

that introduces a

less

life

to have

would

die.

it.

a

list

should always appear on the same page as the

start

of the

okay for a table or figure to appear on a different page than the sentence In this case, the sentence introducing the table or figure

tence. For example,

compare the

if

there

right

is

no additional

text after the

and wrong ways of introducing

should end with

introductory sen-

a figure that appears

a different page:

Figure 8 on page 24 illustrates packet passing

in

a token ring network, (right)

Figure 8 on page 24 illustrates packet passing

in

a token ring network: (wrong)

ft:

288

compound

list:

dense below 4°C.

period rather than a colon, even

on

the only

Without the second property, most aquatic

of the

an excellent solvent.

•

The sentence introducing list.

is

start

Punctuation > Colons

Quotation Marks

In fiction, quotation

marks bound the beginning and end of a spoken

line, as in

the fol-

lowing example:

Woody

said, "And,

think

I

what we've got here

is

a

dead shark."

Technical prose offers very few opportunities for such juicy dialog. However, quotation

marks allow technical authors

to

bound an

exact quote from another written source, as in

the following example:

Newton's

A

First

remain

to

in

Law

of

Motion states, "Every object

in

a state of uniform motion tends

that state of motion unless an external force

solid alternative to quotation

marks

is

to place

verbatim

is

text

applied to

on

it."

separate lines, indented

as follows:

Newton's

First

Law

of

Every object

Motion states the following: in

a state of uniform motion tends to remain

that state of motion unless an external force

Some

in it.

sources advise writers to indent only those quotes that are longer than ten physical

lines. Personally,

I

also find

it

are using that are a

word

little

in a special

wink

much

shorter quotes.

a particular

word or phrase

useful to indent

You may place quotation marks around marks

applied to

is

to indicate that

you

or nonstandard way. For example, the following quotation

to the reader to indicate that

you

realize that robots are

gender-

neutral:

The robot was dressed

in

a tuxedo

when

"he" answered the door.

Avoid using quotation marks that might hamper tion

marks

in the

clarity.

For example, consider the quota-

following sentence:

To remove the locked

file,

issue the

command, "rm

*.lck."

Punctuation > Quotation Marks

289

1

The preceding example might required part of the

fool the reader into thinking that the closing period

command. When

there

is

remove the quotation marks and do one of the following •

Mark

•

Place the special text

The

latter

a

instead:

the special text with a different font.

option

is

on

a separate line.

the better approach. For example, the following version removes any

possible confusion about

To remove the locked

rm

is

even a remote chance of confusing readers,

what

file,

command

to enter:

issue the following

command:

*.lck

Straight Quotes versus Curly Quotes

Many word

processors provide the following two kinds of quotation marks:

which look

•

"straight quotes,"

•

"curly quotes," which look a bit like the

a little like the

number

Generally speaking, you should use curly quotes. The only

umenting sample program code. For example, note straight quotes:

printf("The answer is %d.", my answer);

II! 290

Punctuation > Quotation Marks

1

numbers 66 and 99

common exception

is

when doc-

that the following code contains

GLOSSARY

A

abstract

brief

A

active voice

summary of a

lengthy proposal or lab report.

sentence in which the subject acts on the object. For example, Cheetahs

chase zebras

an active-voice sentence because the subject (cheetahs) verbs the

is

object (zebras). Active- voice sentences are usually shorter, clearer, and ful

than passive-voice sentences. In addition, most readers for

ond language

prefer active voice sentences.

Compare

whom

The people who will read your document or view your Web members for a Web site are also called visitors.

In

A

figure typically consisting of a set of rectangles with

some block diagrams, an

artist

is

a sec-

to passive voice.

audience

block diagram

more power-

English

site.

The audience

embedded

labels.

draws arrows between the rectangles to connect

related structures visually. In other block diagrams, the artist stacks rectangles vertically to

symbolize

a hierarchy.

The typographic mark

bullet a

new element

bulleted

list

A

list

—

in

the elements of a bulleted

numbered

business plan

A

—

that denotes the start of

list.

which each element begins with

the elements in a bulleted

to

usually a filled circle or square

in a bulleted

list

a bullet. Unlike a

have no specific order. In other words,

list,

the

list

would

still

numbered if

list,

you rearrange

have the same meaning. Compare

list.

proposal aimed

at getting

money

to start a

new

business or expand an

existing business.

business proposal

A

proposal aimed

at selling a

new

idea (typically, for a

new product)

within an existing company.

S Glossary

291

A combination of a

callout

and

textual label

points to a particular part and gives

A

caption

it

a pointer (a line

a

segment or arrow).

name. Compare

to

embedded

brief description of a figure, typically prefaced by a number.

tions appear just below figures.

The captions

A callout

label.

By custom, cap-

associated with a table are sometimes

called tides.

chunk

A

short, discrete unit or lesson

at the

top of a

A

color blindness

new

a particular topic. Typically,

condition in which people (usually

have trouble distinguishing

conjunction

on

A word

each chunk starts

page.

among

men

of European background)

certain colors.

(such as and or but) that connects two related thoughts within the

same sentence. Compare

A

context-sensitive help

to transition.

kind of online help system that automatically provides the

rele-

vant help information based on the user's current situation. With context-sensitive help, users

do not have

A manual

cookbook-style manual consists of a

copy editor

A

list

type of literary editor

A

to

who

letter that

list

in

which each topic

of instructions.

looks for errors in spelling, punctuation, and

developmental

formal business

file.

cookbook

similar to a culinary

of materials followed by a numbered

grammar. Compare

cover letter

to search for the appropriate help

editor.

introduces an attached

document (such

as a

resume or proposal).

CSS

Abbreviation for Cascading Style Sheets. a distinct

design spec

In

and consistent look across an

some

developmental editor

industries, another

A

be written. whole.

HI 292

Glossary

name

type of literary editor

improve organization and writing

doc project plan

A CSS entire

style.

enables

Web

Web

developers to maintain

site.

for a low-level technical spec.

who

acts as a sort of writing tutor to

Compare

to

copy

editor.

A planning document that summarizes an entire documentation set A doc project plan explains how each manual will fit into a cohesive

to

A

doc spec

planning document that summarizes

a single

usually define the manual's audience, length,

manual

to be written.

Doc

and approach. Good doc specs

specs

also

provide a detailed outline and schedule.

dynamic content

Program-generated

Web information. Unlike static content, dynamicwho is visiting the site or what a given visitor

content can change depending on

wants to do with the

elevator speech

A

site.

very short oral presentation to a venture capitalist or banker in which

an entrepreneur describes an idea for a new company.

A numbered

element

embedded

label

A

or bulleted item within a

label placed directly

list.

on the part of a

figure that

it

describes.

Compare

to callout.

Scrap of information (often a citation) that appears in a note

endnote

document. Endnotes and footnotes

typically contain the

same

at the

end of

a

sort of information,

but footnotes appear on the source page, and endnotes appear

at

the end of the

document.

establishing shot

A

graphic that shows an entire scene or the exterior of an object. Pho-

tographers, cinematographers, and graphic artists like to present an establishing shot prior to graphics that provide details.

FAQ

FAQs are a staple of newsgroups and name suggests, a FAQ is a list of common

Abbreviation for frequently asked questions. other Internet communications. As the

questions and their answers.

fixed-width font

A

font in

horizontal space.

A

font

footnote

to variable-width font.

graphically consistent set of characters.

1

functional spec

1.

which each character consumes exactly the same amount of

Compare

A numbered

note

In

many

(like this

industries, another

one) that appears

at

the

name

for a high-level technical spec.

bottom of a page. Formal

writing reserves footnotes for certain kinds of citations. However, writing

many

may

more

also use footnotes for digressions. In general, technical

scientific

casual scientific

and technical

and technical

documentation shouldn't contain too

footnotes.

Glossary

293

guide

A manual more advanced than a tutorial, intended for more experienced readers. Good guides generally teach topics by presenting a series of examples, moving from moderately easy to more advanced ones.

A

header

title

within a document. The definition of header has shifted somewhat in the

couple of decades. Originally, a header was any

last

Now though, many people do not

think of a chapter

only those sections or subsections within

documents

are hierarchic; thus,

headers,

be the

example Dennis

first

in a

The simplest example

book

called

example,

summarizes

home

title.

header and believe that

chapter can be called headers. Headers

typically contain first-level headers, second-level

in

possible example.

A

Hello World example should typ-

any technical book. The phrase comes from the

The

C Programming Language by

first

Brian Kernighan and

Ritchie.

A

high-level technical spec (for

including a chapter

as a

and so on.

Hello World example ically

a

title,

title

sales,

a

detailed internal

document aimed

marketing, and documentation).

A

at a

multiple departments

high-level technical spec

product about to be developed.

The Web page intended to serve as a starting point for visitors to a Web site. Web sites should contain a home page, although it is not a given that visitors will browse to the home page before viewing other Web pages. Compare to secondary page

All

pages.

HTML

Acronym

for Hypertext

Markup Language. The bread-and-butter encoding

lan-

and plain

text.

guage of the Internet, consisting of simple tags (such as

for a

HTML

is

a subset

of

a larger

encoding scheme called

SGML

list)

(Standard Generalized

Markup Language). imperative verb

A

verb that acts as a

on the tube, the word put

jargon

The words,

among layout

phrases,

is

command. For example,

and acronyms

themselves but that are

that practitioners use

unknown

to

literary editor

is

sometimes

when communicating

Ill Glossary

Compare

text)

on

a virtual

called composition.

A person who reviews documentation with an eye

rather than the technical content.

types of literary editors.

Put the cap

most nonpractitioners.

The geometric arrangement of graphic elements (graphics and or physical page. This

294

in the sentence

an imperative verb.

Copy

editors

toward the writing

and developmental

to technical editor.

editors are

itself

two

A

low-level technical spec

who will

prints for

manual

how

document aimed at the engineers on a project new product or technology. Such specs provide the blue-

detailed internal

be implementing a

the engineering team should implement the product or technology.

A document

that teaches readers

how

to

perform

a task, use a product, or

master

a technology.

monospaced

Another name

font

A manual

nonverbal manual

numbered

A

list

list

for fixed-width font.

that contains only graphics

which each element

in

be listed in a particular order.

then

it

should be

If

is

and no words.

preceded by an integer. The elements must

you can change the order of the elements

a bulleted rather

than a numbered

in the

Generally, any documentation presented in soft-copy format. However,

online help

people

now

mean

reserve the term online help to

list,

list.

most

a particular kind of soft-copy

documentation that provides quick, concise explanations of how

to accomplish spe-

cific tasks.

pace

The

rate at

which

sents a lot of

a

document

new information

new information

a little

presents information.

A

fast-paced

per page, while a slow-paced

document

document

per page. Slow-paced documents spend

pre-

presents only

more time

explain-

ing assertions than fast-paced documents.

Instructions that produce a consistent layout across a set of

page template Strict

adherence to

a

Web

pages.

good page template helps produce professional-looking Web

sites.

Grammatical and

parallelism

ments within a list

is

a list

a singular

logical consistency

should be completely

noun, then

all

among

parallel.

all

the elements in a

For example,

subsequent elements

in the

if

list

the

first

list.

Ele-

element

in

should be singular

nouns.

parenthetical clause thetical clause

passive voice

A

A is

digression, example, or elaboration within a sentence.

bounded by

a pair

sentence in which the subject

is

the sentence Zebras are chased by cheetahs

(cheetahs)

is

A

paren-

of commas, parentheses, or dashes.

acted

is

upon by

the object. For example,

in passive voice

because the subject

verbed upon by the object (zebras). Use passive-voice sentences spar-

ingly in technical

and

scientific writing.

Compare

to active voice.

:

Glossary

K 295

PDF

Abbreviation for PostScript Display Format. With the right software, authors can convert documents written in any word processor to PDF. Users with the right soft-

ware (such

point

as

Adobe Acrobat Reader) can view or

print

PDF documents.

typography, a unit for measuring the height of fonts, as measured from the top

In

of the highest

The point

is

letter to the

one of the

bottom of the

lowest.

slipperiest units of

world; for example, every

letter in a

One

point

measurement

12-point font

is

1/72 of an inch high.

is

in the entire

mathematical

shorter than the expected 1/6

inch.

In layout, anything that directs a reader's eyes. For

pointer

because readers will look

PowerPoint

in the direction that the

example, an arrow

arrow

is

is

a pointer

pointing.

Software manufactured by Microsoft (and part of the Microsoft Office Suite)

that helps organize presentations.

preproposal

A brief summary

—

to creating a full proposal.

A

proposal

written request to

company, or develop

a

either written or oral

—

do something

program

—

in

Question-and-Answer (Q-and-A) Format is

which the body

a question,

level

of

a

manual

A manual

in

to reviewers prior

the waters.

example, to perform research,

exchange for

money

start a

or other resources.

A style of documentation

in

which each header

formula for estimating the appropriate educational

document's audience. For example,

determine that a given document

reference

for

test

text answers.

A mathematical

readability quotient

— communicated

Use the preproposal to

which

is

a certain readability

quotient might

appropriate for sixth graders.

details are presented as a series of discrete topics.

Reference manuals usually provide rather terse descriptions compared to guides or tutorials.

release notes

A document

popular

in software

features of a software release, plus any

products that typically describes the

known bugs and bugs

new

fixed in the current

release.

research proposal

A

written request to research a problem in exchange for

money

or

other resources.

rule

Ill 296

A

line that divides cells

.

Glossary

within a table or forms a border on the outside of

a table.

A

run-on sentence

sentence that

sans-serif font

A

should be. Alternatively,

it

a sentence that

two or three separate sentences.

which none of the characters are rendered with

font in

(serifs) at the

longer than

is

the writer should divide into

more readable than

endpoints. Sans-serif fonts are

tiny

notches

little

serif fonts in online

documents.

A

screenshot

of an image that appears on a computer monitor. Software

digital picture

documentation

for

end

and system administrators often

users, installers,

features

screenshots.

Any Web page

secondary page

A

serif font

font in

(serifs) at the

which

Web

in a

other than the

site

home

page.

or most of the characters are rendered with tiny

all

endpoints. In hard-copy documents, serif fonts are

little

notches

more readable than

sans-serif fonts.

SGML Acronym

Standard Generalized Markup Language.

for

Both are tagging languages, but

shading

In tables, a gray or colored

SGML

sidebar

is

A

HTML

much

which every other row

is

stricter

background on individual

tables use alternate-row shading in

row

parsers are

cells

is

a subset

of SGML.

than browsers.

or on rows.

Many

shaded and the alternate

unshaded.

block of text and/or graphics displayed in a shaded background that contains

an interesting digression off the main topic.

significance statement

A

one- or two-page explanation of why proposed research

is

important or relevant.

static

content visit.

stet

An

Information within

Compare

editor's

to

a

Web site

that looks the

same

to

every visitor on every

dynamic content.

comment

that

means "ignore my comments." An

corrections in the margin of a

book and then changes

his

editor

who

mind would

writes

some

write stet next

to his corrections.

structured documentation

time-series graphs

A

guide

in

which the document consists of a

A two-dimensional graph

in

set

of chunks.

which the x-axis represents the passage

of time.

Glossary

297

title

The name of a document. typically prefaced

by

a

In addition, a

number

Shade Trees). By custom,

(for

title is

also a brief description of a table,

example, Table 3-1 Characteristics of

a table title

appears just above each

table.

Common

Compare

to

caption.

TOC tone

Abbreviation for table of contents.

The emotional character of a document. Most

technical

documents have

a serious,

business like tone, although science writing for lay audiences often has a lighter,

Some modern consumer-product manuals even

friendlier tone.

present a slightly

flip

or sarcastic tone.

A word

transition

or phrase that helps a reader

move smoothly to

the next sentence. Pop-

ular transitions in technical writing include however, for example,

When

used, transitions are usually the

word or phrase

first

and

therefore.

in a sentence.

Compare

to conjunction.

tutorial

A manual aimed

variable-width font izontal space.

Web

site

getting a neophyte started

font in which different characters

Compare

An

Web

on

a

new

occupy

topic.

different

amounts of hor-

to fixed-width font.

The information displayed

page

stitutes a

Web

A

at

at a specific

URL. A

collection of

Web

pages con-

site.

organized collection of Web pages, typically focused on providing informa-

tion about a discrete topic or to serve a distinct audience.

A section of a hard copy document that does not contain any ink, or a section Web page that is rendered in the background color and pattern of that Web page.

white space

of a

298

Glossary

BIBLIOGRAPHY

•

Aired, G., C. Brusaw, ton,

•

MA:

and W. Oliu. 2000. Handbook of Technical Writing: 6th

ed. Bos-

Bedford/St. Martin's.

Chicago Editorial

Staff.

2003. Chicago

Manual

of Style: 15th ed. Chicago: University

of Chicago Press. •

and C.

Friedlan, A.

Folt.

2000. Writing Successful Science Proposals.

New

York City:

Yale University Press. •

Harlow, William M. 1957. Trees of the Eastern and Central United States and Canada. Toronto: General Publishing Company. This book served as source for the sample

Chapter

tables in •

8.

Kernighan, B. and D. Richie. 1988. The

C Programming

Language: 2nd ed. Upper

Saddle River, N): Prentice-Hall PTR. •

National Science Foundation. 2004. Grant Proposal Guide. Arlington, VA:

•

Nielsen,

J.

2000. Designing

Nielsen,

).

and M.

•

Web

Tahir. 2002.

Usability. Indianapolis:

Homepage

New

July.

Riders Publishing.

Usability. Indianapolis:

New

Riders Pub-

lishing.

•

Perelman,

L,

J.

Paradis,

Scientific Writing. •

Rich,

S.

and

E. Barrett. 1998.

The Mayfield Handbook of Technical

&

Mountain View, CA: Mayfield Publishing Company.

and D. Gumpert. 1985. Business Plans That Win $$$.

New York City: Harper

and Row. •

Strunk, W.,

MA:

E. B.

White, and R. Angell. 2000. The Elements of Style: 4th ed. Needham,

Pearson.

•

Tarutz, Judith. 1992. Technical Editing. Reading,

•

Tufte,

Graphics •

Tufte,

MA: Addison-Wesley.

Edward. 2001. The Visual Display of Quantitative Information. Cheshire, CT: Press.

Edward. 1997. Visual Explanations. Cheshire, CT: Graphics

Press.

ibhography

299

Web •

Sites

Purdue University. Department of Horticulture and Landscape Architecture. (www.hort.purdue.edu/hort).

•

Riofrio,

Garden

II 300

Glossary

Marianne. Ohio State University Extension Fact Soils,

(ohioline.ag.ohio-state.edu).

Sheet. Fertilizing Vegetable

1

1

INDEX

Symbols

aligning

graphics, 108 :),

254

text in graphics,

97

alternate explanations, 120

anecdotes in footnotes,

1

23

Arial font, 273

abbreviations, punctuation in, 287

as pointers, 104

abstracts, 187

focus, 106

definition of, 291 in lab reports,

articles in

216

research proposals, 191

Acrobat

Distiller,

magazines, 196 in high-level technical specs,

of Web

209

site visitors,

166

PowerPoint presentations, 234, 243

acronyms, 33

winning

consistency, 33

for nonnative speakers, 14 in,

5

it,

audience, 9

expanding, 33

agitated, 17

appropriateness, 4

287

becoming, 19

active voice, 46

book proposals,

definition of, 291

195, 196, 197

breadth, 12

lab reports, 47

business plans, 198

strengths, 47

ADHD example,

assembly

attention span

177

Acrobat Reader, 176, 177

punctuation

Websites, 167 arrows, 97

above (word usage), 69

college freshmen, 112

216

home

defining in a

adjectives, 36 in business proposals,

203

page, 164

defining in a preface,

1

50

definition of, 291

administration manuals

doc spec example, 23

screenshots, 93

documentation project plans, 25

Adobe, 177

educational level, 10

advanced topics, 138

emotional

state, 17

adverbs, 36 in business proposals, affect air

203

empathy

for, 19

engaging, 190, 227

(word usage), 42

examples,

pressure example,

1

experience,

algebraic formulas

expertise,

explanations of,

1

1

14

14 1

1

12

for this

book, 20

Index

301

7

formula-based rules,

bold, 279

12

1

gaining empathy for, 19

in graphics,

97

Book of Lists, The, 63 book proposals, 181, 195

getting attention of, 5

giving directions, 68 glossaries, 151

audience, 196

high-level technical specs, 206

contents, 196

market research data, 9

example marketing section, 197

medium and motivation

message, 18

of,

preproposals, 182 strategy, 195

1

older, 278

boring writing, 5

peers, 238

breadth

:

question-and-answer format,

audience, 12

18

1

research proposals, 190

breathing to relax, 246

summary of, 20

brevity

superiors, 238

tone

in

online help, 143

Web sites,

secondary pages, 174

167

and

visualization, 9

British readers

Website, 162

browsers, default fonts, 167

auditory learners, 242

budgets

baseball, 15

in research proposals, 191

bugs in release notes, 147,

B

bullet symbols,

back matter, 24

bulleted

in

PowerPoint presentations, 235

in

Websites, 105

in business proposals,

lists,

64

capitals, 71

definition of, 291

background information

elements

204

in

in tutorials, 136

in,

65

cookbook-style manuals, 134

introducing, 69

bar charts

length of elements, 66

in business proposals,

205

number of elements

PowerPoint presentations, 239

and native culture, becoming the audience, 19 baseball terms

before-and-after graphics, 89 beginner's

64

definition of, 291

background colors

mind and

tutorials, 136

below (word usage), 69

BentonGothic

font, 273

beta tests

15

in,

parallel,

70

periods, 71

PowerPoint presentations, 236 second-level, 236 vs. vs.

embedded numbered

lists,

50

lists,

63

business plans, 181, 198

audience, 198

online help, 144

bios of consultants, 186

examples, 186 research proposals, 191

block diagrams, 97 definition of, 291

white space example, 107

body language, 245

Index

64

online help, 144

documentation, 268 biographies, 185

302

148

tracking, 266

contents, 199 definition of, 291

marketing, 199 vs.

business proposals, 202

business proposals, 201, 202 analysis,

203

definition of, 291

3

1

example, 204, 205

block diagrams, 97

marketing, 203

contrasting, 94

summary, 213

discontinuities, 105

vs.

business plans, 202

hyperlinks, 173

by comparison (transition), 56

PowerPoint presentations, 235

by contrast (transition), 56

Websites, 167 color blindness, 95, 96 definition of, 292

column headers 74

in tables,

callouts, 90

commands

definition of, 292

parenthetical clauses, 52

275

that vs. which, 41

can (word usage), 41

comparing technical writing

capital letters

components

captions

list

high-level technical specs, 207

alignment of graphics, 108

low-level technical specs, 21

definition of, 292

conceptual entries in indexes, 158

editing, 263, 269

concise

tables,

cascading

83

example

style sheets (see

CSS)

of, 5

FAQs, 179

cells

phrases, 40

amount of text, 80

secondary pages, 174

units of measure, 75

sentences, 49

centering

writing, 4

graphics, 108

CERN,

conclusions, 6

181

lab reports,

Chicago Manual of Style, 283 Chinese language,

224

PowerPoint presentations, 228 conjunctions

1

Chinese restaurants metaphor, 49

definition of, 292

choppy sentences,

semicolons, 286

51

chunks, 138

starting a sentence with, 57

chunks, definition

of,

292

citations in lab reports, clarity, in

footers, 263

graphics, 97, 98

comments, 261, 269

headers, 263

planning documents, 201

in research proposals,

cliches,

transitions, 57

consistency

4

in internal

in

vs.

225

business plans, 198

in editorial

click

to engineering,

8

elements, 71

in list

imperative verbs)

commas, 284

font height, 277 fonts,

(see

190

of terminology, 99

speaking, 243

of word usage, 33

40

reference pages, 140

here hyperlinks, 172

client-server architecture example, clip art in

labels, 127

content management software, 163 1

15

PowerPoint presentations, 239

context-sensitive help, 143 definition of, 292

clutter in layout, 107

contingency plans, 188

colons, 288

contrast in color or shading, 105

color

cookbook

style

manuals, 134

Index

303

1

definition of, 292

footnotes, 123

example

online help, 144

135

of,

summary

copy

edit,

copy

editors, 259, 263

of,

269

sidebars, 122

within a sentence, 52

definition of, 292

Courier-New

fonts,

cover

184

letters,

directions, giving, 68

274

discontinuities, 105

Discussion section of lab reports, 223

definition of, 292

doc project plans

research proposals, 191

definition of, 292

CPT, 216

doc specs

criticism, 241,

269

definition of, 293

e-mail messages, 255

example, 23

cross-cultural examples, 16

how

cross-references, 140

issues

CSS, 278

outline example, 24

definition of, 292

e-mail, 252

of, 2

reviewers

list,

summary

of,

24 28

documentation

cultural references, 15 e.e.,

24

list,

purpose

cultural differences, 15, 16

cummings,

to write, 22

253

beta tests, 268 conflicts,

267

cost of screenshots, 94 for

programmers, 116

guides, 138, 139

Danish language, 13

pace, 122

dashes, 285

question-and-answer format, 118

parenthetical clauses, 52

reference manuals, 140

data analysis in research proposals, 194

schedules, 267

dates, in different countries, 16

sets,

defects in documentation, 266

25

structured, 138

definitions in glossaries, 151

documentation planning, 21—28

descriptions

documentation project plans

examples

in,

114

example

of geometric figures, 127

how to

precise, 126

of,

26

write, 25

summary

of,

28

design of research proposals, 194

documentation specifications

design specs, 210

documents

definition of, 292

legal,

developmental editor definition of, 292

60

drop-dead-date

in

cover

dull writing, 5

diabetics example, 165

dynamic content, 163

diagnostic information, 140

definition of, 293 1

18

dictionary-style documentation, 140 digital

photography, 100

enhancing with

line art, 101

establishing shot, 102 digressions, 124

304

Index

doc specs)

optimum number, 25

developmental editors, 259

dialog in question-and-answer format,

(see

e.e.

cummings, 253 259-269

editing,

letters,

184

3

work, 262

a superior's

empathy with

encyclopedic documentation, 140

diplomacy, 262

en-dashes, 285

distributing, 263

endnotes, 123

260

effective,

definition of, 293

e-mail messages, 252

engaging audiences,

4, 5

hardcopy, 265

pace, 122

online, 265

PowerPoint presentations, 227, 234,

relationship with writer, 261, 262 relationship with writers, 260

243 engineering

schedules, 267

audience analysis of product, 144

summary, 269

compared with

time allocated, 267

context-sensitive help systems, 143

tracking bugs, 266

cost of inventions, 49

your

own document, 264

critical analysis

technical writing, 8

of writing, 45

documentation process, 266

educational level

of audience, 10

editing process, 264

of this book, 20

e-mail blasts, 255

management, 202, 238

(word usage), 42

effect

plans for teams, 212

elements definition of, 293 in bulleted lists, in

numbered

role of

lists,

parallel,

documentation plans, 21

specs, 209

65 67

engineers

audience for

length of, 66

70

this

book,

xvii

biographies, 186

block diagrams, 97

periods, 71 elevator speeches,

1

82

definition of, 293

em

readers, 19, 138

copy editor, 263

bureaucracy, 252 business proposals, 202

commenting code, 140

dashes, 285

e-mail messages,

249—256

Danish and Swedish, 13

cowardice, 254

editing, 259

debates in, 267

e-mail messages, 251

editing, 252

fluff,

miscommunications, 255

in

Pickford Paradox, 249

jargon, 32

problems with, 250

low-level technical specs, 210

summary, 256

45

management, 32

Pickford Paradox, 249

vs.

formal documents, 251

planning documents, 201

vs.

telephone conversations, 254

presenting revolutionary ideas, 189 proposals, 181

wars, 147

embedded

labels, 91

definition of, 293

embedded

lists,

commas

in,

50, 64

284

emergencies, in index, 17

emoticons, 254

emotional state e-mail messages, 256

of audience, 17

resistance to marketing, 36 sensitivity,

255

specs, 201

success and failure, 7

wardrobe, 245 writing level, 3

English as a pervasive technical language,

1

English as a second language, 13, 47

e-mail messages, 256

Index

305

5

equipment Ernest

in lab reports,

Hemingway, and

219

hot

air

and cold

air, 5

hurricanes, 194

in reference pages,

hyperlinks in body text, 172

140

establishing shot, 102, 103

in glossaries, 151

European Organization

in reference pages,

for Nuclear Re-

European readers and English, 1

140

introduction in lab reports, 218

search, 181

examples,

1

high-level technical specs, 208

readability, 50

error codes, 17

13

it

and

they, 39

jargon and audience,

14

abstract in lab reports,

216

1

juggling, 101, 102

abstract in proposals, 187

length of, 138

active voice, 46

low-level technical specs, 21

air pressure,

Materials section of lab report, 219

1

14

beyond the obvious, 125

metaphors,

1

biographies, 186

mysteries in

Web sites,

bones

in little finger,

90

15

166

native culture, 15, 16

Web sites,

book proposals, 197

navigators in

boring, 5

online help, 145, 146

business proposals, 204

170

passive voice, 48

client-server architecture,

PowerPoint

1 1

lists,

236

color to grayscale, 125

PowerPoint presentations, 233

Conclusion section of lab reports, 224

precision descriptions, 127

contingency plans, 188

preface, 150

cookbook-style manuals, 135

programming documentation,

cover

question-and-answer format,

letter,

184

design and methods of research proposals,

digital

reference pages, 141

Results section in lab reports, 222

Discussion section of lab reports, 223

revolutionary proposals, 189

doc specs, 23

sans-serif fonts, 273

documentation project plans, 26

serif fonts,

DOS and UNIX commands,

significance statements, 192

78

273

table of contents, 153, 154

electric force, 16

of Web

electron microscope, 150

title

elevator speeches, 182

to explain rules, 112

e-mail messages, 250, 252

tutorials, 137

sites,

165

white space, 108

engaging, 5

Experimental Procedure

in lab reports,

220

you, 38 exceptions to rules, 112

example

firewall, 119

for color blindness,

96

for this book, 20 1

14

glossary, 152

graphics in PowerPoint, 239 gravitational force, 112, 113

guides, 139

Hello World, 116

Index

16

19

research proposal objectives, 193

photography, 101

gas pressure,

1

1

release notes, 148

194

digestive system, 91

306

1

of,

1

13

exclamation points, 287

Experimental Procedure section in lab ports, 220

explanations,

1

12

alternate, 120

precise, 126

eyes as pointers, 104, 106

re-

5

1

in

PDF, 176

instead of quotation marks, 290 face

mask example, 142

italics,

failure

lists,

in

cookbook

in

proposals, 1X8

style

familiarity of topic,

manuals, 134

Lucida Console, 274 paragraphs, 277

1

points, 277

FAQs, 178

PostScript, 281

definition of, 293 vs.

question-and-answer format,

PowerPoint presentations, 235 1

18

sans-serif,

246

fear of speaking,

272

screen resolution, 278

feedback on documentation, 268

serif,

Fenster, 197

273

summary, 282

fiction

tables,

audience motivation, 17

277

279

titles,

conjunctions, 57

True-Type

Henry James, 52

Type

1,

PostScript, 281

vs.

281

linear access, 18

variable width, 274

metaphors,

Web pages,

1

1

reputation of author, 196 vs.

1

weight of, 272, 273 footers

figures

editing, 263

(sec also graphics)

colons, 288

fonts,

definition of, 293

doc specs, 22 example, 119

fixed-width fonts, 274 fluffy phrases,

275

footnotes, 123

editing, 263

firewall

278

Websites, 167

technical writing, 3

word usage,

final

279

277

40

online help, 144 for

example (transition), 56

foreign phrases, fonts, 279

formulas

focus, 104

explaining, 112

discontinuities, 105

on page, 106

of technical writing, 8 readability, 50

focused audience, 12

frequently asked questions (see

(word usage), 69 fonts, 271-282

Freud, Sigmund, 123

following

callouts,

277

front matter, 24

function names,

captions, 277

Courier New, 274

FAQs)

1

16

functional specs (see high-level technical specs)

default, 273

definition of, 293

example of online help, 146 fixed-width, 274 foreign phrases, 279

Caramond

hard copy documents, 275

general help, 143

headers, 277

generic verbs, 34

height of, 277 in graphics, in

HTML,

97

176

font, 273

geometric descriptions, 127 glossaries, 151

example

of, 152

Index

307

jargon, 32

fonts, 275,

276

PowerPoint presentations, 240

Goldberg, Isaac quote, 4

Web sites,

vs.

161

golden rule of indexing, 155

he (word usage), 37

Goldman, William, 123

headers

grammar 13

politically correct, 37

grammatically parallel

grand

finale,

graphics,

294

definition of,

and native language,

{see parallelism)

editing, 263 fonts, 275,

277

74

in tables,

numbering, 60

244

85-109

table of contents, 153, 154

alignment on page, 108

height of Web pages, 174

before and after, 89

Hello World examples,

block diagrams, 97

1

16

definition, 294

clutter, 88, 107

help systems (see online help)

consistency, 98

helping the reader, 4

digital

photography, 100

establishing shot, 102

Hemingway,

Ernest, 50

hierarchies

FAQs, 179

bulleted

geometric descriptions, 126

headers, 60

gray, 96

65

lists,

high-level technical specs, 201, 206

homepage, 166 in lab reports,

analysis,

220

introducing, 99 labels, 90, 91,

207

definition of, 294

example, 208

summary, 213

99

layout, 104

highlighting in screenshots, 94

online, 88

home

pages, 164

orienting readers, 92

audience definition, 164

photography and

definition of, 294

line art, 101

pointers, 104

engaging, 166

PowerPoint presentations, 239, 240

stating

summary, 109

summary, 180

telling a story, 142

three-dimensional, 98

white space, 107

graphs detail in,

purpose

of,

164

tone, 167

honesty biographies, 185 hyperlinks, 172

88

time-series, 86, 87

gravitational force example, 112, 113

lab reports, 221

horizontal scrolling, 174

HTML

grayscale, 96

, 164

guides, 138

definition of,

definition of, 294

294

online help, 143 relationship to

SGML, 280

sample of a guide, 139

H

308

vs.

PDF,

176, 177

humor

happen (word usage), 34

in

FAQs, 179

hard-copy documents

in

PowerPoint presentations, 230

Index

1

in prefaces,

graphics, 99

149

hurricane examples, 194

lists,

introduction of

research proposals, 193

document, 6

hyperlinks, IX

graphics, 99, 288

color, 173

lab reports, 217, 218

glossaries, 151

in

body text of Web FAQs, 179

sites,

172

lists,

new

PowerPoint presentations, 228

online help, 144

proposals, 184

in reference pages, 140

right

number

target

60, 69, 288

terms, 33, 118

paragraphs, 55, 58

170

in navigators,

in

69

Websites, 164

glossary, 152

in

1

of, 173

research proposals, 194

windows, 173

tables,

hypotheses, 193

288

topics, 136

Websites, 175

Discussion section of lab reports, 223 in lab reports,

216

yourself, 182

in research proposals, 193

(word usage), 42 italics, 279 it's

in graphics, its

97

(word usage), 42

ideas per sentence, 51 ideas, revolutionary,

1

89

illustrations {see graphics)

imperative verbs, 67

Japanese culture

definition of, 294 in other

baseball, 15

personal checking accounts, 16

words (transition), 56, 120

jargon, 32

indexing, 155

conceptual entries, 158

audience experience,

editing, 269

definition of, 294

entries for emergencies, 17

e-mail messages, 256

Websites, 167

examples, 156

javadoc, 140

length, 155

permuting terms,

1

57

jokes in footnotes, 123

precise entries, 156

information density, 122

Web

1

pages, 167

in

PowerPoint presentations, 230

juggling examples, 101, 102, 103

ingredients in cookbook-style manuals, 134

inoculation, 11, 189

business proposals, 203 installation

manual screenshots, 93 documents, 201—213

internal planning

key principles of technical writing, 4

Internet, 161

distributing

random

K Kernighan and Ritchie, 116

documents on, 176

access, 161

search boxes, 171

introducing colons, 288

King Kong

social climber

business proposal, 204 high-level technical spec, 208

low-level technical spec, 21

King, Stephen, 128

Index

309

length of elements, 66

numbered, 67 lab reports,

215-226

abstracts,

216

citations,

225

of equipment in lab reports, 219 parallel,

%

PowerPoint presentations, 236

Discussion section, 223

equipment

section headers, 60

219

list,

summaries

Experimental Procedure section, 220

to break

introduction, 217

References section, 225

literary editing,

269

literary editors,

259

long sentences, 49

Results section, 221, 222

causes of, 50

sections in, 215 of,

reducing, 51

226

low-level technical specs, 201, 210

tense, 35

definition of, 295

labels in graphics, 90, 91,

99

example, 211

consistency, 127

summary, 213

language, native, 13 lay

72

of,

up blocks of text, 122

types of, 63

materials section, 2 19 passive voice, 47

summaries

70

periods in, 71

Conclusion section, 224

Lucida Console font, 274

audience

lying in a biography, 185

explaining rules, 112 tables, 73

using jargon, 32

M

Websites, 167 layout, 104

Macintosh fonts, 281

definition of, 294

eyes

Web

magazine

on page, 106

managers

learning styles, 242 legal

documents,

18,

learning styles, 242

60

motivation, 202

length

manuals, 133-159

of books, 23

definition of, 295

of documents, 25 of elements in numbered

67

in

documentation project plans, 26

indexes of, 155

of PowerPoint presentations, 228

motivation to read, 17

of sentences, 49

nonverbal, 142

of sections, 60

line art, 101

63-72

summary

citations,

tutorial

225

colons to introduce, 288

commas

in,

284

directions, 68

embedded, 50 fonts,

275

introducing, 69

Index

reference, 140

structured documentation, 138

bulleted, 64

310

guides, 138 lists,

of paragraphs, 58

levels

lists,

196

articles,

males and color blindness, 95

pages, 168

of,

1

59

example, 137

tutorials, 136 vs.

online help, 143

maps gray, 96 in tourist areas, 92

market defining in proposal, 187

5

1

New

marketing

book proposals, 197

in

non-goals

204

in high-level technical specs,

207

PowerPoint presentations, 232

in

usage), 41

nonverbal manuals, 142 definition of, 295

numbered

McNealy, Scott quote, 227

adjectives, 36

lists,

67

capitals, 71

media in

doc specs, 23

nonparallel (see parallelism)

nouns versus NSF, 191

materials in lab reports, 219

may (word

in

non-native speakers, 13

in business plans, 198, 199

in business proposals, 203,

Jersey, 271

newspaper layout, 168

engineers' dislike of, 36

definition of, 295

documentation project plans, 27

plan, 25

directions, 68

225

in citations,

medium and the message, 18 men and color blindness, 95

in

menus, documenting, 145

online help, 144

metaphors,

parallel,

1

in research proposals, 1

194

50

miscommunications in e-mail, 255 misunderstandings and language, 13

monospaced

mood

manuals, 134

70

periods, 71

native culture, 15

methods

style

introducing, 69

1

microscopy example,

cookbook

vs.

bulleted

vs.

embedded

lists,

63

lists,

50

numbering section headers, 60

274

fonts,

of audience,

1

2

motivation of audience, 17

movies as cross-cultural examples, 16

objectives in research proposals, 193

occur (word usage), 34

multimedia, 175 musical punctuation, 283

offensive photographs, 16

okay (word usage), 15

mysteries

PowerPoint presentations, 233

online editing, 265

Websites, 166

online help, 143 best practices, 144

categories, 143

definition of, 295

N

examples, 145, 146

National Science Foundation, 181

opening chapter of a book, 6

native culture, 15

ordinal

numbers

in directions,

dates, 16

organizing writing, 6

examples, 16

outline in doc specs, 24

for this

68

book, 20

native language, 13

e-mail messages, 256 for this

book, 20 pace, 122

simple words, 14 navigators in

Web

sites,

170

two-level, 171 nevertheless (transition), 56

definition of, 295

of speaking, 243

PowerPoint presentations, 234 page counts, 25

Index

311

page layout, 106

in

definition of, 295

isllfl

ilflfSs ::mgmr:m

Web site

{see

Web pages)

wmm mm :;;|||l||;

mm $wm

entries, 157

and

line art, 101

establishing shot, 102

Palatino-Linotype font, 273

offending, 16

panic attacks while speaking, 246

telling a story, 142

Websites, 167

paper

;Ji§i:

elements, 71

photographs

page-oriented documentation, 138

pages in a

list

permuting index

page templates, 168, 169

advantages and disadvantages, 18

picas,

editing on, 265

Pickford Paradox, 249

pros and cons, 18

pictures (see graphics)

296

:

vs.

Web sites,

pie charts in business proposals, 205

161

planning, 201—213

paragraphs fonts,

SBii

documentation projects, 21—28

275

informational content of graphics, 240

for failure, 188

length of, 58

media, 25 Websites, 162

one-sentence, 58

opening sentence, 6

pointers, 104 definition of, 296

pace, 122

summary of,

l#S3il

eyes, 106

61

points, 277

transitions, 59

definition of, 296

parallelism definition of, 295 in tables, in tables

politically correct

pop-up graphic

79

of contents, 154

section names, 60

PowerPoint, 296

parenthetical clauses, 52

PowerPoint presentations, 227—247 attention span, 243

parts, 33 labelling in graphics,

90

naming, 127 passive voice, 46

fear of speaking,

fonts,

235

e-mail messages, 252

grand

finale,

lab reports, 47

graphics, 239, 240

lengthy sentences, 50

interruptions, 229

241

244

introductions, 233

past tense, 35

learning styles, 242

pauses, 283

lists,

PC fonts, PDF

marketing speak, 232

281

in

mystery

documentation project plan, 27

HTML,

236

176, 177

style,

opening

slides,

organizing, 228

:

periods, 287

Index

233

number of slides, 229

:::i^* :i:>::S !

312

246

definition of, 295

vs. :i'

color, 235

final slide,

definition of, 296

;

background images, 235 body language, 245 body slides, 234

acceptable uses, 48

weaknesses, 47

;||ff||||

269

parentheses, 287

parsimony, 8

;J|riff|

88

positive reinforcement, 261,

PostScript fonts, 281

definition of, 295

fellf^K

grammar, 37

detail,

pace, 234

231

1

pre-show, 244

cover

printing, 240

definition of, 296

question-and-answer sessions, 24

elevator speeches,

relaxation techniques, 246

importance

184

letters,

1

82

of, 181

speaking, 243, 245

inoculating against skepticism, 189

speech, 244

preproposals, 182

230

starting, 229,

research (see research proposals)

summary of, 247 what

revolutionary ideas, 189

summary, 200

238

to superiors,

to wear,

243

templates, 183

within your company, 202

practicing speaking, 246

preceding (word usage), 69

public speaking, 241, 243 crippling fear of, 246

precision

publishers, 195

index entries, 155

punctuation, 283-290

precision descriptions, 126

colons, 288

prefaces, 149

commas, 284

example, 150 preliminary doc specs, 22

dashes, 285

preproposal

emoticons, 254

hyphens, 285

definition of, 296

preproposals, 182

periods, 287

present tense, 35

quotation marks, 289 semicolons, 286

pre-show, 244

primary keys

vs.

columns, 77

table

Princess Bride, The, 123

principles of technical writing, 4 principles, explaining,

12

1

QA

printing

HTMLvs.PDF,

PowerPoint presentations, 240 professional secrets,

summary

1

1

1

programming documentation,

beta-tests,

116, 117

Question-and-Answer

268

documentation, 267

Question-and-Answer format,

quotes, 290 project description in proposals, 191

documentation project plans

pronouns, 37, 38, 39

1

18

definition of, 296

example

project plans, 25 (see also

(see

format) quality assurance

— 129

129

of,

(see quality assurance)

Q-and-A format

176

of,

1

19

Question-and-Answer sessions, 241 PowerPoint presentations, 228

proposal review committees, 190

questions in FAQs, 178

proposals, 181-200

quotation marks, 289

abstracts, 187

biographies, 185

books, 195 business, 202

business

(set'

business proposals)

R2D2, 16 random access of information,

18

business plans, 198 readability quotients, 50

commonalities, 181

definition of, 296

contingency plans, 188 readers (see audience)

convincing reviewers, 189

Index

313

WM,,

reference manuals, 140

soft-copy documents, 276

Web sites,

definition of, 296

example, 141

167

schedules

motivation to read, 17

doc specs, 22

References section of lab reports, 225

documentation project plans, 25

release notes, 147

in

definition of, 296

example in

of,

documentation

projects, 267

in high-level technical specs,

documentation project plans, 26

27

compared with

repetition, 6, 50

science,

reports, status, 253

scientific writing

research proposals, 181, 190, 193

audience, 190

technical writing, 8

creativity, 5

value of, 3

contents of, 191

scientists

contingency plans, 188

aiming documents

data analysis, 194

audience for this book,

design and methods, 194

common

methods, 194

editing, 259

methods and

materials, 194

at,

36

fashion sense, 245 mysteries, 233

overview of experiment, 194

Q-and-A format,

significance statements, 192

research proposals, 190

strategy, 190

xvii

language, 13

objectives, 193

118

revolutionary proposals, 189

Research section of lab reports, 224

technical reviews, 259

resolution of different media, 18

writing and, 8

results in research proposals, 194

writing lab reports, 215

Results section in lab reports, 221

screen resolution and fonts, 278

reviewing documents, 259

screenshots, 93

revolutionary ideas, 189

cost of, 94

rhetorical questions, 114

definition of, 297

romantic-comedy rows of a

style

table, sorting,

of overviews, 231

78

rules in tables, 81

highlighting, 94 scrolling

HTMLvs.PDF, 176 Web sites,

alternative, 82

search boxes in

definition of, 296

search engines, 162

rules,

209

schematics, in documentation project plan,

148

explanations of, 112

run-on sentences, 45, 51 definition of, 297

171

secondary pages, 162 definition of, 297

summary, 180 second-level index entries, 157 sections, 55, 60, 153

numbering headers, 60

summary safety

equipment, 142

safety issues

and tone, 121

sans-serif fonts, 272

self-editing, 128

semicolons, 286

definition of, 297

sentence fragments in bulleted

examples

sentence variety, 35

of,

273

hard-copy documents, 275 height of, 277

314

of, 61

self-doubt, xx, 128

Index

passive voice, 48

sentences,

45—53

lists,

65

3

1

active voice, 46

soccer in examples, 15

choppy, 51

soft -copy

documents

editing, 265

deleting unnecessary, 53 digressions, 52

278

fonts, 276,

software documentation

long, 50

number of words

in,

quotation marks, 290

50

opening a section, 60 opening

in a

paragraph, 6

release notes, 148

software manuals

passive voice, 46

cookbook example, 135

per paragraph, 58

example of a guide, 139

repetition, 50

guide example, 139

run-on, 45, 51

nonverbal treatment, 142

semicolons, 286

tutorial

short

vs.

long, 49

starting with conjunction, 57

speaking, 243

strong, 47

fear of,

summary of,

53

functional, 206

variety of, 48

high-level technical, 206

272

definition of, 297

examples

201-213

design, 210

transitions, 56

serif fonts,

of,

273

low-level technical, 210

speech, 243

hard-copy documents, 275

lessons

height of, 277

from professional entertainers,

244

overcoming

soft-copy documents, 276 serifs,

246

specifications {see specs)

specs,

topic, 55

example, 137

sorting rows in a table, 78

272

fear,

telling jokes,

SGML, 280

246

230

transitions, 57

definition of, 297

spell checkers, 263, 264,

266

context problems, 269

shading discontinuities, 105 in tables,

82

split infinitives,

13

Spring Into Series, 138

she (word usage), 37

stage freight, 241

short sentences, 49

Standard General Markup Language, 280

sidebars, 122

stapler

signal-to-noise ratio

starting a project, 128

fonts, 275,

276

static

sentences, 45

stet,

definition of, 297 silent films,

size

Web site,

1

163

297

straight quotes,

290

strong verbs, 34

relation to reference 1

subheads within

Web

manuals, 140

pages, 175

subjects

slang

e-mail messages, 256 native culture, 15 slides (see

content in a

1

structured documentation, 138

249

of fonts, 277

skeptical readers,

ruler example,

definition of, 297

readability, 50

significance statements, 192

and

PowerPoint presentations)

smiley faces, 254

active vs. passive, 46

missing, 47

obscuring, 48 sublists,

65

Index

315

3

:

:

sugar, spoonful of, 261

organizing, 77

summaries

parallel,

business proposals, 2

doc specs, 28

rules in, 81

documentation project plans, 28 editing,

269

summary

282

titles,

graphics, 109

vs.

high-level technical specs, 213

home

pages,

lab reports, lists,

shading, 82 sorting, 78

e-mail messages, 256 fonts,

79

referring to, 76

1

of,

primary keys, 77

tables of contents, 153

editing, 263,

18(3

226

84

83

269

entries for emergencies, 17

example, 154

72

low-level technical specs, 213

target audience for this

manuals, 159

teams of engineers, 212

paragraphs, 61

technical editing, 259

PowerPoint presentations, 247 professional secrets, 129

book, 20

see also editing

summary of, 269

proposals, 200

technical editors, 259

secondary pages, 180

technical overview in high-level business specs, 207

sections, 61

sentences, 53 tables,

technical writing

compared with engineering,

84

Websites, 180 words, 43

summarizing

8

creativity, 5

formulas, 8

in technical writing, 6

overview, 3—8

Sun Microsystems, 227

parts of speech, 36

support organizations and release notes, 147

practicing, 4

Swedish language, 13

success and failure, 7

synopsis

theorems, 4

business proposals, 204

topic sentences, 55

high-level technical specs, 207, 208

value of, 3

low-level technical spec, 211

vs. fiction, 3 vs.

painting, 4

technology overview high-level technical specs, 208

technology overview in technical specs, 208

73-84 amount of text

tables,

television in cells,

audience reaction, 73 captions, 83

affect vs.

on reading,

Web sites,

161

166

Tell 'em, 6

colons, 288

temperature graphs, 86, 87, 88

column headers, 74

templates

editing, 263

proposals, 183

font height, 277

Web pages,

fonts, 275

Websites, 169

for variety, 122

tense, 35

introducing, 76

terminology

leftmost columns, 77

316

80

Index

168

1

definition, 298

consistent, 99

example

testing

documentation, 268 jokes,

Twain, Mark,

230

Type

online help, 144 technical writing that

(word usage), 41

that

is

and engineering,

8

1

xvii,

147

fonts, 281

typography

fonts)

(5ft'

(transition), 56, 120

u

(word usage), 67

theti

of, 137

relation to guides, 138

theorems of technical writing, 4 there

(word usage), 34, 35

is

UK

readers and baseball, 15

they (word usage), 37

unfortunately (transition), 56

thoughts per sentence, 51

units of

measurement

variable

names, 116, 117

in tables,

75

three-dimensional graphics, 98

time allocation

in

PowerPoint presentations,

228, 229

time of day for presentations, 234

Times

New Roman

font, 273

variable width fonts, 274

time-series graphs, 86, 87 variety definition of, 297 tire

example,

1

changing pace, 122

14

PowerPoint presentations, 234

titles

of PowerPoint

question-and-answer format, If slides,

231

of tables, 83

to

VCs

venture capitalists)

verbs, 34

be (word usage), 34

TOC,

(see

venture capitalists, 181

of Web pages, 164

compared

to adverbs, 36

298 simplicity of, 14

tone, 121 strong, 34 definition of, 298 tense, 35

FAQs, 179

varying, 35

Websites, 167

Verdana

topic sentences, 55 tourist

font, 273

Websites, 167

maps, 92 viruses

and hyperlinks, 172

tracking documentation bugs, 266 visual cues in layout, 104

trademarks, 263 visual learners,

242

transistors, 32

visualizing audience, 9 transitions, 56, 57

vocabulary

between paragraphs, 59 non-native speakers, 14 definition of, 298

semicolons, 286 vs.

conjunctions, 57

translating

from English, 14

troubleshooting

cookbook-style manuals, 134 in reference pages,

w wardrobe of engineers, 245

140

warranty cards, 24

weather glossary,

1

52

troubleshooting manual, 27

weather station doc spec, 23

True-Type

Web

fonts, 28

tutorials, 136

pages associating related, 174

Index

317

; :

women and word usage

brevity, 174

definition of, 298 fonts,

278

above, 69

adverbs and adjectives, 36

height of, 174

mm.

plan for a

color blindness, 95

Web site,

162

42

affect,

secondary, 174

below, 69

subheads, 175

can, 41

summary, 180

effect,

Ill

templates, 168, 169

employ, 14

li^Ifl

vs. traditional

mwi

width

of,

1

documentation, 175

following, 69

happen, 34

74

writing for, 175

he, 37

Will

writing in, 175

it,

mi

Websites, 161-180

it's,

color, 167

its,

comparison to paper medium, 161 :-:f!N

:

E:i;i':.Si:

creating

list

42

37 42 42

occur, 34

of pages, 162

okay, 15

definition of, 298

preceding, 69

dynamic content, 163

pronouns, 38

homepages,

she, 37

162, 164

liilli

hyperlinks in body text, 172

that, 41

'IliS

introduction, 164

then, 67

iiiis

layout, 104

there

mysteries, 166

to be, 34

navigators, 170

use, 14

34

page templates, 168, 169

utilize,

planning, 162

wasteful vs. frugal, 40

purpose

secondary pages, 162 static

you, 38

words

content, 163

for experts, 32

summary, 180 title of,

jargon, 32 length of sentence, 50

164, 165

summary

tone, 167 vs. television,

14

which, 41

of, 162

search engines, 165