Spring Into Technical Writing for Engineers and Scientists: For Engineers and Scientists

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. Cover 1 Contents 10 Preface 18 SECTION 1 Planning to Write 24 CHAPTER 1 The Quest 26 Technical Writing Theorems 27 Technical Writing Can Be Creative 28 Tell ’Em 29 The Value of Technical Communication to You 30 Comparing Technical Writing to Engineering and Science 31 CHAPTER 2 Audience 32 General Education Level 33 Experience and Expertise 34 Breadth of Audience 35 Native Language 36 Native Culture 38 Audience Motivation 40 Medium and the Message 41 Becoming the Audience 42 Summary of Audience 43 CHAPTER 3 Documentation Plans 44 Document Specifications (Doc Specs) 45 Doc Specs: Sample 46 Documentation Project Plans 48 Documentation Project Plan: Sample 49 Summary of Documentation Specifications 51 SECTION 2 Writing: General Principles 52 CHAPTER 4 Words 54 Jargon 55 Consistency 56 Verbs 57 Adjectives and Adverbs 59 Pronouns: He, She, and They 60 Pronouns: You 61 Pronouns: It and They 62 Fluffy Phrases 63 Commonly Confused Words 64 Summary of Words 66 CHAPTER 5 Sentences 68 Active Voice and Passive Voice 69 Active Voice Is Better 70 When Is Passive Voice Okay? 71 Short = Sweet 72 Causes of Long Sentences 73 One Sentence = One Thought 74 Parenthetical Clauses 75 Summary of Sentences 76 CHAPTER 6 Paragraphs and Sections 78 Sentence Transitions 79 Paragraph Length 81 Paragraph Transitions 82 Sections 83 Summary of Paragraphs and Sections 84 CHAPTER 7 Lists 86 Bulleted Lists 87 Elements in Bulleted Lists 88 The Length of Each Element 89 Numbered Lists 90 Directions 91 Introductions to Lists 92 Parallel Lists 93 Summary of Lists 95 CHAPTER 8 Tables 96 Column Headers 97 Units of Measure 98 Arrangement of Columns and Rows 100 Parallelism in Tables 102 Amount of Text in Cells 103 Rules 104 Shading 105 Captions 106 Summary of Tables 107 CHAPTER 9 Graphics 108 Time Series 109 Extra Detail in Online Graphics 111 Before and After 112 Callouts versus Embedded Text 113 Graphics That Orient Readers 115 Screenshots 116 Color Blindness 118 Block Diagrams 120 Text That Supplements Figures 122 Technical Photography 123 Line Art Enhances Technical Photographs 124 Big Picture First, Then Details 125 Layout: Controlling Focus 127 Layout: Keeping Eyes on the Page 129 Layout: White Space 130 Summary of Graphics 132 CHAPTER 10 Professional Secrets 134 Explanations of Formula-Based Rules 135 Examples 137 Examples by Metaphor 138 Examples for Programming Documentation 139 Question-and-Answer Format 141 Question-and-Answer Format Example 142 In Other Words 143 Tone 144 Pace 145 Footnotes and Other Digressions 146 Beyond the Obvious 148 Precision Descriptions 149 The Hardest Part of Writing 151 Summary of Professional Secrets 152 SECTION 3 Writing: Specific Kinds of Documents 154 CHAPTER 11 Manuals 156 Manual Style: Cookbooks 157 Cookbook Example: Installing the Carambola Server 158 Manual Style: Tutorials 159 Tutorial Example: Getting Started with HTML 160 Manual Style: Guides 161 Guide Example: Creating HTML Headers 162 Manual Style: Reference Manuals 163 Reference Example: The pr1me Utility 164 Manual Style: Nonverbal Manuals 165 Online Help: Overview 166 Online Help: Best Practices 167 Online Help Examples 168 Release Notes 170 Release Notes Example: Carambola Web Server Version 3.7 171 Prefaces 172 Preface Example 173 Glossaries 174 Glossary Example: Tropical Weather Terms 175 Tables of Contents 176 Indexes 178 Indexes: Providing Concise Entries 179 Indexes: Permuting Terms 180 Indexes: Providing Entries for Concepts 181 Summary of Manuals 182 CHAPTER 12 Web Sites 184 Plans 185 Home Page: Specify Purpose and Audience 187 Home Pages: Engage the Reader’s Imagination 189 Home Pages: Set the Tone 190 Page Templates 191 Navigators and Search Boxes 193 Hyperlinks in Body Text 195 Secondary Pages 197 Text in Web Sites 198 PDF versus HTML 199 Frequently Asked Questions (FAQs) 201 Summary of Web Sites 203 CHAPTER 13 Proposals 204 The Proposal before the Proposal 205 Adherence to the Proposal Template 206 Proposal Element: Cover Letters 207 Proposal Element: Biographies 208 Proposal Element: Abstracts 210 Proposal Element: Contingency Plans 211 Proposals for Revolutionary Ideas 212 Research Proposals 213 Research Proposals: Significance Statements 215 Research Proposals: Objectives and Hypotheses 216 Research Proposals: Design and Methods 217 Book Proposals 218 Book Proposal: Example Marketing Section 220 Business Plans 221 Summary of Proposals 223 CHAPTER 14 Internal Planning Documents 224 Business Proposals 225 Business Proposal: Example 227 High-Level Technical Specs 229 High-Level Technical Spec Example 231 Low-Level Technical Specs 233 Low-Level Technical Spec Example 234 Summary of Internal Planning Documents 236 CHAPTER 15 Lab Reports 238 Abstract 239 Introduction 240 Materials 242 Experimental Procedure 243 Results 244 Discussion 246 Conclusion 247 References 248 Summary of Lab Reports 249 CHAPTER 16 PowerPoint Presentations 250 Organizing a Presentation: The Big Picture 251 The Number of Slides 252 The Opening Moments of a Presentation 253 Introductory Slides: The Traditional Approach 254 Introductory Slides: An Alternate Approach 256 Body Slides: Pace and Variety 257 Mechanics: Fonts and Backgrounds 258 Body Slides: Effective Lists 259 Audience: The Theory of Relativity 261 Graphics 262 The Complexity of a Graphic 263 Question-and-Answer Sessions 264 Different Kinds of Learners 265 PowerPoint Speech: The Basics 266 PowerPoint Speech: Lessons from the Pros 267 PowerPoint Speech: Overcoming Fear 269 Summary of PowerPoint Presentations 270 CHAPTER 17 E-Mail 272 The Essence of the E-Mail Problem 273 Before Hitting the Send Button... 275 After the First Miscommunication... 277 Summary of E-Mail 279 SECTION 4 Editing and Producing Documents 280 CHAPTER 18 Editing and the Documentation Process 282 Editing: What Is It Really? 283 Technical Editing a Peer’s Work 284 Technical Editing a Superior’s Work 285 Copyediting a Colleague’s Document 286 Copyediting Your Own Document 287 Media for Technical Editing 288 Bug-Tracking Systems 289 A Process for Editing 290 Beta Tests for Documentation 291 Summary of Editing and the Documentation Process 292 CHAPTER 19 Fonts and Typography 294 Serif and Sans-Serif Fonts 295 Fixed-Width versus Variable-Width Fonts 297 Serif and Sans-Serif in Hard Copy 298 Serif and Sans-Serif in Soft Copy 299 Font Height 300 Italics and Boldface 302 Consistency and Convention 303 True-Type versus PostScript Fonts 304 Summary of Fonts and Typography 305 CHAPTER 20 Punctuation 306 Commas 307 Dashes and Hyphens 308 Semicolons 309 Periods 310 Colons 311 Quotation Marks 312 Glossary 314 A 314 B 314 C 315 D 315 E 316 F 316 G 317 H 317 I 317 J 317 L 317 M 318 N 318 O 318 P 318 Q 319 R 319 S 320 T 320 V 321 W 321 Bibliography 322 Index 324 A 324 B 325 C 326 D 327 E 327 F 329 G 330 H 331 I 331 J 332 K 332 L 332 M 333 N 334 O 334 P 334 Q 336 R 336 S 336 T 338 U 340 V 340 W 340 Y 341 Teaches you how to write for an international audience; use active voice to communicate with confidence and authority; and produce effective lists, tables, and graphics. This work also helps you develop winning research, business, and book proposals; and present Power Point presentations.