Spring Into Technical Writing for Engineers and Scientists / Edition 1

by Barry Rosenberg

Overview

The fastest way for professionals to master technical writing!

You’re a technical professional, perhaps a programmer, engineer, or scientist. You are not a professional writer, but writing is part of your job (specs, manuals, proposals, lab reports, technical presentations, Web content, data sheets, and so on).

Welcome. This book is for you. It’s all you need to clearly communicate technical ideas to any audience—technical or nontechnical—and motivate them to act.

Barry J. Rosenberg organizes every facet of effective technical writing into more than 175 short, concise, fast-paced tutorials. You’ll find loads of examples (what to do and what not to do) plus start-to-finish instructions for writing exactly the kinds of documents you need to create.

Need specific solutions? This book’s bite-size, visual, high-efficiency format delivers them instantly. Dig in, get started, and get results!

• Make all your documents and presentations clearer, more concise, and more compelling
• Understand your audience, and target your content appropriately
• Learn how to write for an international audience
• Use active voice to communicate with confidence and authority
• Produce effective lists, tables, and graphics
• Create useful examples
• Write effective manuals and release notes
• Implement solid technical Web sites
• Develop winning research, business, and book proposals
• Create and present compelling PowerPoint presentations
• Write e-mails that don’t ignite flame wars
• Learn how to integrate documentation development into best engineering practices

Downloadable examples are available on the Web.

Product Details

ISBN-13:	9780131498631
Publisher:	Pearson Education
Publication date:	05/17/2005
Series:	Spring Into... Series
Pages:	352
Product dimensions:	6.90(w) x 9.10(h) x 0.90(d)

About the Author

Barry Rosenberg is the author of more than sixty corporate technical manuals, primarily on programming. An experienced instructor, Barry has taught everything from high school physics to weeklong corporate seminars on data structures. Most recently, he spent four semesters at MIT, where he taught advanced technical writing. Barry currently works as the documentation manager at 170 Systems.

Read an Excerpt

The character of Fortuna—brilliant, sexy heiress to the Gambini empire, and two-time winner of both the Grand Prix de Monaco and the Fields Prize in mathematics—is strictly fictional. In fact, all the characters in this book—whether living or dead, implied or extrapolated, fictional or nonfictional—are fictional. The people, the companies, the situations, and everything presented as 100% factual are completely fictional. In fact, I don’t even really exist; “Barry Rosenberg” is just a composite author formed by the publishing company from several actual technical authors.¹

To be completely honest, this book contains no character named Fortuna. All that stuff about everything being fictional is fictional. The information in this book is the truth and factual and asymptotically approaches satisfactual. I’m real, too. I’m a real technical writer, manager, and teacher, working in the software industry. I occasionally teach technical writing to engineering and science students at a surreal place called MIT. Who Should Read This Book?

I’ve aimed this book at engineers and scientists who must write about stuff. Perhaps you are an esteemed 60-year-old scientist who has long realized how integral writing is to the job. Perhaps you are a 20-year-old science student who is taking a class in technical writing because “you have to.” Perhaps your career is somewhere between those two points, and you find it painful to write the specs and reports that your job requires, and you are sick of your peers scribbling “I don’t understand” in the margin of everything you write, and you just wishthat there were a way to make writing go a little easier.

Perhaps you are already a good writer and would like to take your writing to another level.

Let me re-emphasize: This book is for engineers and scientists, not professional writers. I’ve assumed that you don’t much care about the difference between transitive and intransitive verbs—you only want to write better. How Is This Book Organized?

I’ve organized this book into the following four sections:

• Section 1 introduces the field and explains how to plan documentation.
• Section 2 teaches you the nuts and bolts of technical and scientific writing.
• Section 3 explains how to write particular kinds of engineering and scientific documents.
• Section 4 covers editing and producing documentation.

The book concludes with a glossary of writing terms. What’s Unusual about This Book?

This book—like the other books in the Spring Into... Series—provides the following eccentricities:

• Each topic is explained in a discrete one- or two-page unit called a chunk.
• Each chunk builds on the previous chunks in that chapter.
• Most chunks contain one or more examples. I believe that good examples provide the foundation for almost all useful technical documents.
• Many chunks contain sidebars and “Quantum Leap” sections, which provide helpful, if sometimes digressive, ancillary material.

I assume that you are a very busy person for whom the time spent in the very act of buying this book was excruciatingly painful. To repay that incalculable opportunity cost, I’ve adopted the chunk style of presenting information so that you can learn as rapidly as possible.

Finally, I hope you’ll find this book fun to read. If you’ve paid good money for a book—no matter what the topic—boring text is a slap in the face. Writing a Book about Writing Books

I had this great cognitive psychology professor as an undergraduate. Three times every week, he lectured us on current research on memory. Without fail, in the middle of every lecture, he ran back to his office to fetch the notes he had forgotten. He followed in the same vein as my acne-scarred dermatologist, my cross-eyed ophthalmologist, and my sister’s speech pathology professor, who had a regrettable stuttering problem.

All those people haunted me while I wrote this book. I kept wondering whether I was the writing professor who couldn’t write well. After writing each sentence, I stepped back and asked, “Am I practicing what I’m preaching?” Friends, it got ugly. I’d write a sentence, then erase it, then rewrite it, and erase it, and on and on it would go. Writing suddenly became very difficult for me. My self-doubt reached biblical proportions.

Then it hit me—I had become the audience. I had re-experienced the pain of writing. This was a breakthrough because “becoming the audience” is one of the most important states a technical or scientific writer can achieve. Yes, pain is good.

May I write about something else now?Where Can You Download Examples Used in This Book?

You can download a subset of the examples from this book by browsing to the following URL: www.awprofessional.com/title/0131498630What Is Fake in the Examples?

I am honor bound to proclaim the following disclaimers about the examples:

• All of the companies mentioned (Dexco Unlimited, Carambola Publishing, Pravda Mills, Googleplex, Calispindex, and so forth) in this book are figments of my imagination. If I accidentally picked the name of a real enterprise, then it was purely a coincidence.
• The sample biographies used in this book are of fictitious people.
• The sample proposals and lab reports exist solely to teach you how to write better proposals and lab reports; they are not based on real proposals or real experiments.

Who Helped Me Write This Book?

Mark Taub—the publisher of this book—wisely appointed the following three primary reviewers, all of whom were completely amazing:

• Mary Lou Nohr—brilliant wit of technical editing—who turned out beautifully detailed and highly humorous responses to my drafts. Mary Lou’s comments were, themselves, of publishable quality.
• Chris Sawyer-Laucanno—poet, biographer, expert in ancient languages, and technical writing professor at MIT—who offered insightful and crucial criticism.
• Nicholas Cravetta—engineer and writer—whose tough love kept me on the straight and narrow.

Much of the material in this book originated from a technical writing course I taught for four semesters at MIT. I am indebted to Jim Paradis, Les Perelman, and Steve Strang for giving me the opportunity and the guidance to teach that course.

Julie Nahil did a wonderful job guiding this book through its final editorial phases.

Other material in this book comes from conversations with great technical writers, including Jim Garrison, Marietta Hitzemann, John Abbott, and Judy Tarutz. Special thanks to Kenyon College and to the technical writing department at Rensselaer Polytechnic Institute for preparing me for the technical writing life. Thanks also to Roger Stern and Arthur Lewbel for random props, information, and jokes. Gigantic thanks to the brilliant engineers at 170 Systems, who served as the inspiration for much of this book.

Finally, enormous thanks to my wife Marilyn, who took care of far too many day-to-day details over the last year so that I could have the time to write this book.

Note
1. Much the same way that a nineteenth-century publishing syndicate formed “Mark Twain.”

Table of Contents

Preface.

I. PLANNING TO WRITE.

1. The Quest.

Technical Writing Theorems

Technical Writing Can Be Creative

Tell 'Em

The Value of Technical Communication to You

Comparing Technical Writing to Engineering and Science

2. Audience.

General Education Level

Experience and Expertise

Breadth of Audience

Native Language

Native Culture

Audience Motivation

Medium and the Message

Becoming the Audience

Summary of Audience

3. Documentation Plans.

Document Specifications (Doc Specs)

Doc Specs: Sample

Documentation Project Plans

Documentation Project Plan: Sample

Summary of Documentation Specifications

II. WRITING: GENERAL PRINCIPLES.

4. Words.

Jargon

Consistency

Verbs

Adjectives and Adverbs

Pronouns: He, She, and They

Pronouns: You

Pronouns: It and They

Fluffy Phrases

Commonly Confused Words

Summary of Words

5. Sentences.

Active Voice and Passive Voice

Active Voice Is Better

When Is Passive Voice Okay?

Short = Sweet

Causes of Long Sentences

One Sentence = One Thought

Parenthetical Clauses

Summary of Sentences

6. Paragraphs and Sections.

Sentence Transitions

Paragraph Length

Paragraph Transitions

Sections

Summary of Paragraphs and Sections

7. Lists.

Bulleted Lists

Elements in Bulleted Lists

The Length of Each Element

Numbered Lists

Directions

Introductions to Lists

Parallel Lists

Summary of Lists

8. Tables.

Column Headers

Units of Measure

Arrangement of Columns and Rows

Parallelism in Tables

Amount of Text in Cells

Rules

Shading

Captions

Summary of Tables

9. Graphics

Graphics

Time Series

Extra Detail in Online Graphics

Before and After

Callouts versus Embedded Text

Graphics That Orient Readers

Screenshots

Color Blindness

Block Diagrams

Text That Supplements Figures

Technical Photography

Line Art Enhances Technical Photographs

Big Picture First, Then Details

Layout: Controlling Focus

Layout: Keeping Eyes on the Page

Layout: White Space

Summary of Graphics

10. Professional Secrets.

Explanations of Formula-Based Rules

Examples

Examples by Metaphor

Examples for Programming Documentation

Question-and-Answer Format

Question-and-Answer Format Example

In Other Words

Tone

Pace

Footnotes and Other Digressions

Beyond the Obvious

Precision Descriptions

The Hardest Part of Writing

Summary of Professional Secrets

III. WRITING: SPECIFIC KINDS OF DOCUMENTS.

11. Manuals.

Manual Style: Cookbooks

Cookbook Example: Installing the Carambola Server

Manual Style: Tutorials

Tutorial Example: Getting Started with HTML

Manual Style: Guides

Guide Example: Creating HTML Headers

Manual Style: Reference Manuals

Reference Example: The pr1me Utility

Manual Style: Nonverbal Manuals

Online Help: Overview

Online Help: Best Practices

Online Help Examples

Release Notes

Release Notes Example: Carambola Web Server Version 3.7

Prefaces

Preface Example

Glossaries

Glossary Example: Tropical Weather Terms

Tables of Contents

Indexes

Indexes: Providing Concise Entries

Indexes: Permuting Terms

Indexes: Providing Entries for Concepts

Summary of Manuals

12. Web Sites.

Plans

Home Page: Specify Purpose and Audience

Home Pages: Engage the Reader's Imagination

Home Pages: Set the Tone

Page Templates

Navigators and Search Boxes

Hyperlinks in Body Text

Secondary Pages

Text in Web Sites

PDF versus HTML

Frequently Asked Questions (FAQs)

Summary of Web Sites

13. Proposals.

The Proposal before the Proposal

Adherence to the Proposal Template

Proposal Element: Cover Letters

Proposal Element: Biographies

Proposal Element: Abstracts

Proposal Element: Contingency Plans

Proposals for Revolutionary Ideas

Research Proposals

Research Proposals: Significance Statements

Research Proposals: Objectives and Hypotheses

Research Proposals: Design and Methods

Book Proposals

Book Proposal: Example Marketing Section

Business Plans

Summary of Proposals

14. Internal Planning Documents.

Business Proposals

Business Proposal: Example

High-Level Technical Specs

High-Level Technical Spec Example

Low-Level Technical Specs

Low-Level Technical Spec Example

Summary of Internal Planning Documents

15. Lab Reports.

Abstract

Introduction

Materials

Experimental Procedure

Results

Discussion

Conclusion

References

Summary of Lab Reports

16. PowerPoint Presentations.

Organizing a Presentation: The Big Picture

The Number of Slides

The Opening Moments of a Presentation

Introductory Slides: The Traditional Approach

Introductory Slides: An Alternate Approach

Body Slides: Pace and Variety

Mechanics: Fonts and Backgrounds

Body Slides: Effective Lists

Audience: The Theory of Relativity

Graphics

The Complexity of a Graphic

Question-and-Answer Sessions

Different Kinds of Learners

PowerPoint Speech: The Basics

PowerPoint Speech: Lessons from the Pros

PowerPoint Speech: Overcoming Fear

Summary of PowerPoint Presentations

17. E-Mail.

The Essence of the E-Mail Problem

Before Hitting the Send Button...

After the First Miscommunication...

Summary of E-Mail

IV. EDITING AND PRODUCING DOCUMENTS.

18. Editing and the Documentation Process.

Editing: What Is It Really?

Technical Editing a Peer's Work

Technical Editing a Superior's Work

Copyediting a Colleague's Document

Copyediting Your Own Document

Media for Technical Editing

Bug-Tracking Systems

A Process for Editing

Beta Tests for Documentation

Summary of Editing and the Documentation Process

19. Fonts and Typography.

Serif and Sans-Serif Fonts

Fixed-Width versus Variable-Width Fonts

Serif and Sans-Serif in Hard Copy

Serif and Sans-Serif in Soft Copy

Font Height

Italics and Boldface

Consistency and Convention

True-Type versus PostScript Fonts

Summary of Fonts and Typography

20. Punctuation.

Commas

Dashes and Hyphens

Semicolons

Periods

Colons

Quotation Marks

Glossary.

Bibliography.

Index.

Preface

The character of Fortuna—brilliant, sexy heiress to the Gambini empire, and two-time winner of both the Grand Prix de Monaco and the Fields Prize in mathematics—is strictly fictional. In fact, all the characters in this book—whether living or dead, implied or extrapolated, fictional or nonfictional—are fictional. The people, the companies, the situations, and everything presented as 100% factual are completely fictional. In fact, I don’t even really exist; “Barry Rosenberg” is just a composite author formed by the publishing company from several actual technical authors.¹

To be completely honest, this book contains no character named Fortuna. All that stuff about everything being fictional is fictional. The information in this book is the truth and factual and asymptotically approaches satisfactual. I’m real, too. I’m a real technical writer, manager, and teacher, working in the software industry. I occasionally teach technical writing to engineering and science students at a surreal place called MIT.

Who Should Read This Book?

I’ve aimed this book at engineers and scientists who must write about stuff. Perhaps you are an esteemed 60-year-old scientist who has long realized how integral writing is to the job. Perhaps you are a 20-year-old science student who is taking a class in technical writing because “you have to.” Perhaps your career is somewhere between those two points, and you find it painful to write the specs and reports that your job requires, and you are sick of your peers scribbling “I don’t understand” in the margin of everything you write, and you just wish that there were a way to make writing go a little easier.

Perhaps you are already a good writer and would like to take your writing to another level.

Let me re-emphasize: This book is for engineers and scientists, not professional writers. I’ve assumed that you don’t much care about the difference between transitive and intransitive verbs—you only want to write better.

How Is This Book Organized?

I’ve organized this book into the following four sections:

• Section 1 introduces the field and explains how to plan documentation.
• Section 2 teaches you the nuts and bolts of technical and scientific writing.
• Section 3 explains how to write particular kinds of engineering and scientific documents.
• Section 4 covers editing and producing documentation.

The book concludes with a glossary of writing terms.

What’s Unusual about This Book?

This book—like the other books in the Spring Into... Series—provides the following eccentricities:

• Each topic is explained in a discrete one- or two-page unit called a chunk.
• Each chunk builds on the previous chunks in that chapter.
• Most chunks contain one or more examples. I believe that good examples provide the foundation for almost all useful technical documents.
• Many chunks contain sidebars and “Quantum Leap” sections, which provide helpful, if sometimes digressive, ancillary material.

I assume that you are a very busy person for whom the time spent in the very act of buying this book was excruciatingly painful. To repay that incalculable opportunity cost, I’ve adopted the chunk style of presenting information so that you can learn as rapidly as possible.

Finally, I hope you’ll find this book fun to read. If you’ve paid good money for a book—no matter what the topic—boring text is a slap in the face.

Writing a Book about Writing Books

I had this great cognitive psychology professor as an undergraduate. Three times every week, he lectured us on current research on memory. Without fail, in the middle of every lecture, he ran back to his office to fetch the notes he had forgotten. He followed in the same vein as my acne-scarred dermatologist, my cross-eyed ophthalmologist, and my sister’s speech pathology professor, who had a regrettable stuttering problem.

All those people haunted me while I wrote this book. I kept wondering whether I was the writing professor who couldn’t write well. After writing each sentence, I stepped back and asked, “Am I practicing what I’m preaching?” Friends, it got ugly. I’d write a sentence, then erase it, then rewrite it, and erase it, and on and on it would go. Writing suddenly became very difficult for me. My self-doubt reached biblical proportions.

Then it hit me—I had become the audience. I had re-experienced the pain of writing. This was a breakthrough because “becoming the audience” is one of the most important states a technical or scientific writer can achieve. Yes, pain is good.

May I write about something else now?

Where Can You Download Examples Used in This Book?

You can download a subset of the examples from this book by browsing to the following URL: www.awprofessional.com/title/0131498630

What Is Fake in the Examples?

I am honor bound to proclaim the following disclaimers about the examples:

• All of the companies mentioned (Dexco Unlimited, Carambola Publishing, Pravda Mills, Googleplex, Calispindex, and so forth) in this book are figments of my imagination. If I accidentally picked the name of a real enterprise, then it was purely a coincidence.
• The sample biographies used in this book are of fictitious people.
• The sample proposals and lab reports exist solely to teach you how to write better proposals and lab reports; they are not based on real proposals or real experiments.

Who Helped Me Write This Book?

Mark Taub—the publisher of this book—wisely appointed the following three primary reviewers, all of whom were completely amazing:

• Mary Lou Nohr—brilliant wit of technical editing—who turned out beautifully detailed and highly humorous responses to my drafts. Mary Lou’s comments were, themselves, of publishable quality.
• Chris Sawyer-Laucanno—poet, biographer, expert in ancient languages, and technical writing professor at MIT—who offered insightful and crucial criticism.
• Nicholas Cravetta—engineer and writer—whose tough love kept me on the straight and narrow.

Much of the material in this book originated from a technical writing course I taught for four semesters at MIT. I am indebted to Jim Paradis, Les Perelman, and Steve Strang for giving me the opportunity and the guidance to teach that course.

Julie Nahil did a wonderful job guiding this book through its final editorial phases.

Other material in this book comes from conversations with great technical writers, including Jim Garrison, Marietta Hitzemann, John Abbott, and Judy Tarutz. Special thanks to Kenyon College and to the technical writing department at Rensselaer Polytechnic Institute for preparing me for the technical writing life. Thanks also to Roger Stern and Arthur Lewbel for random props, information, and jokes. Gigantic thanks to the brilliant engineers at 170 Systems, who served as the inspiration for much of this book.

Finally, enormous thanks to my wife Marilyn, who took care of far too many day-to-day details over the last year so that I could have the time to write this book.

Note
1. Much the same way that a nineteenth-century publishing syndicate formed “Mark Twain.”