Register your product to gain access to bonus material or receive a coupon.
Spring Into Technical Writing for Engineers and Scientists
- By Barry J. Rosenberg
- Published May 17, 2005 by Addison-Wesley Professional.
Book
- Sorry, this book is no longer in print.
Description
- Copyright 2005
- Dimensions: 7" x 9-1/4"
- Pages: 352
- Edition: 1st
- Book
- ISBN-10: 0-13-149863-0
- ISBN-13: 978-0-13-149863-1
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.
Downloads
Example(s)
Download the examples from Spring Into Technical Writing for Engineers and Scientists
Sample Content
Downloadable Sample Chapter
Download the Sample
Chapter related to this title.
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
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.”
Index
Download the Index
file related to this title.