- Shopping Bag ( 0 items )
Using an informal, hands-on approach, this practical guide reviews the basics of good technical writing. It provides a simple, effective system for writing all types of technical documents including letters, memos, minutes, procedures, manuals, proposals, progress reports, and final reports. You will gain a better understanding of the writing process and learn how to: improve the coherence of your writing, write better paragraphs, write better sentences, choose the right word and more.
Writing on the job is never easy, but it doesn't have to be as difficult as most people make it. Why does writing cause so much anxiety and frustration, and what you can do about it? What are the essential characteristics of effective workplace writing? These are the questions this chapter answers.
Treat Workplace Writing as a Craft, Not an Art
Over the years, dozens of people have told me, in one way or another, that they feel a little embarrassed and inadequate because they find it difficult and time consuming to write. What's more, they are often dissatisfied with the results. "I'm sure you don't have these problems," they tell me earnestly. They couldn't be more wrong.
Perhaps the biggest hurdle for most writers is a serious misunderstanding of the nature of writing. They don't realize that writing is difficult and time consuming for everyone. And they don't understand that the only writer who feels fully satisfied with the quality of the finished product is a writer with low standards.
If you were to survey even the most experienced writers, they would probably say that they don't like to write. They might add that sometimes, on a good day, they like to have written-that is, sometimes they can look at what they have made and see that they accomplished quite a bit. There are always problems that remain to be fixed, and sometimes they have to start over, but at least they have created something that wasn't there when they started. That's all they ask of themselves, and it's all you should ask of yourself.
Don't try for perfection when you start to write. The conditions under which you work pretty much rule it out. You don't have all the information you need. You don't have enough time to polish your writing. And you probably get interrupted a lot. Forget about creating the perfect document; try for "excellent" or, maybe, "very effective." Although you can master a number of techniques for improving your writing, it will never turn out flawless.
What is the best way to write on the job? There is no single method; people are just too different. Over the years, we each develop our own ways of carrying out all the tasks we do at work, and writing is no exception. Some people cannot write except on a word processor; others require legal pads and pencils. Some write only in the early morning; others can't accomplish anything until everyone else has left the office.
Despite these individual differences, however, we are beginning to learn quite a bit about successful workplace writing. This book condenses a considerable body of research-and two decades of my own experience consulting with individual writers-into a few basic techniques of workplace writing. If you don't already use some of these techniques, try them out. They may be effective, or at least you may be able to adapt some of them to your own working methods.
Unlearn What You Learned In School
One of the reasons many people have trouble writing on the job is that much of what is taught in school about solving problems and communicating results doesn't apply in the working world. Our writing teachers don't deserve all the blame, although many of them still preach the prohibitive rules-such as never end a sentence with a preposition-that don't make much sense in the working world. Rather, the problem has to do with how schools mold and form the ways we think, which in turn affects the way we approach workplace writing.
In school we learned that the projects we work on were thought up by a teacher to keep us busy, that they have little or nothing to do with real problems. It started in grade school: one train leaves Chicago at noon, traveling eastward at 95 miles per hour, and another train leaves New York at one o'clock, traveling westward on the same track at 90 miles per hour. Our job was to figure out where the two trains would collide. But if they were really hurtling toward disaster somewhere near Pittsburgh, wouldn't it be smarter to get on the radio and try to prevent the crash? Even though our teacher explained that we were doing an exercise to help us learn a set of concepts and mathematical techniques, what we heard was that problems and solutions do not always link up.
In school we learned that our writing should be "at least": at least 1,000 words, at least 10 pages (double spaced), at least something. What the teacher was doing, of course, was asking us to examine the problem in a certain amount of detail. A 2-page report was meant to be a quick overview; a 10-pager was to be more detailed and get into more complex ideas. But what we heard was that the report on Macbeth had to be 1,000 words long. Knowing that even if we were lucky we had only about 500 words to say about the Scottish king, we learned how to start sentences with phrases such as "It is indeed a not unsupportable contention that ..." No wonder a lot of workplace writing sounds as if it were created by people who studied English while growing up on another planet.
In school we learned to tell our reader even the smallest details that led us to our results. The code phrase in math class was "Show your work!" We couldn't just provide the correct answer; that could be attributed to dumb luck or cheating. And even if we got the answer wrong, we might receive partial credit if we could show we used the right methods. The teacher, we knew, would read everything carefully; that's what teachers like to do.
In school we learned to pad our assignments with the biggest words and the most complicated theories we knew. The teacher knew the subject better than we did, of course, and the purpose of the assignment was to show that we knew it too. Never did we have to explain something to someone who really didn't understand what we were trying to say.
In short, we became accustomed to writing to someone who already knew what we had to say but who for some reason wanted us to write long, complicated, detailed answers that solved nonexistent problems.
Focus on What You Know About Writing at Work
If you work for the average company, you know that this approach to solving problems and communicating your findings doesn't work. Most of the people you write to don't have the knowledge, the time, or the interest to read long, complicated documents.
Because of the knowledge explosion over the past few decades, you can't assume that most of your readers know much about your subject. Technical people at your company are busy learning their own subspecialties. And most managers, even those who started out as technical people, can't even hope to stay current with all the fields their workers are researching. For most managers, it's a fulltime job keeping up with the business end of the operation: hiring and performance reviews, long-range planning, quarterly status reports and sales projections, government regulations, and so forth.
Most managers couldn't find the time to read all you've written even if they could understand it; too many documents are landing on too many desks. Photocopiers have contributed quite a bit to the spread of documents in the working world, and electronic mail is speeding up the process even more, because it doesn't take any more time or cost any more money to send the document to a hundred people than to just one.
Even if managers could find the time to read the whole document, they would probably choose not to. Their interest in the document is different from yours. From your point of view, all the information is important. (After all, you did the work because it was necessary, not to keep yourself busy.) Managers realize that the full story is crucial for carrying out the recommendations and documenting the project, but they probably are not very interested in how you did what you did; they assume that your working methods are accurate and professional.
Rather, managers care most about your conclusions and recommendations-in other words, what you found out and what you think ought to be done about it. Unless these sections look bizarre, most managers are perfectly content to skip over the main body of the document.
Characteristics of Effective Workplace Writing
As I will discuss in the next chapter, effective workplace writing meets the needs of its particular audience. To a large extent, your success as a writer depends on how well you have analyzed what your audience needs and prefers. In general, however, it is possible to isolate a number of characteristics of effective workplace writing regardless of the audience. This section briefly describes eight characteristics.
Above all, workplace writing should be honest. Honesty means a number of things-some obvious, some not so obvious. One obvious point is to acknowledge your use of other people's ideas or words by citing them, using whatever documentation system is appropriate in your field.
The issue of honesty in writing is often complicated by the fact that the person doing the writing does not always have the final say about what gets written. Still, writers should take responsibility for what they create. If you realize you are being asked to do something dishonest or unethical-such as lying or distorting information-you are responsible for trying to remedy the situation by appealing to the best instincts and interests of your supervisor. If that doesn't work, you should keep going up the ladder. If nobody in your organization sees things your way and you are confident that a serious problem is occurring or might occur, then it is time to consider blowing the whistle.
Your first responsibility as a writer is not to lie. For instance, if your company manufactures disk drives with an expected life of 150,000 hours, it is, of course, wrong to state that they last 200,000 hours. And you shouldn't misrepresent reality, such as by suggesting that a product design is the result of sophisticated market-research techniques, when all that really occurred is that you had a brief conversation with someone from the marketing department.
A more difficult aspect of honesty concerns what you don't say. For example, you are writing a data sheet for a new product. You know that a number of competing companies make similar products, that some of these are as good as your company's, and that several are even better in a number of ways. Is it your responsibility to describe the ways in which the competitors' products are better than yours? Most people would say no, provided you have been honest in describing yours. A reasonable consumer can be assumed to understand that when different companies make similar products, each is a little bit different.
Keep one important point in mind, however. It is your responsibility to offer as much information as you can about anything that could affect the safety of the person using the product. If, for example, you know that the chainsaw you manufacture can cause serious injury when used improperly, you must do everything you can to explain how to use it the right way. The fact that a competitor's chainsaw incorporates some design innovations that make it inherently safer than yours does not excuse you from the duty to try to prevent injury to the user. You must explain-as effectively as you can-how to prevent injuries, even if in doing so you alert your reader to the inferiority of your design.
Modern trends in liability suits encourage complete honesty in communication. Juries want to see that companies have done everything possible to give their customers full and complete information on which to base their decisions. Honesty is the best policy, both ethically and financially.
Each statement in the document should convey a single meaning that the reader can understand easily.
Unclear writing is expensive. Over a decade ago, a typical letter cost about $10 in labor and materials; the cost now is probably double that (Day 1983). But these dollar figures are misleadingly low because of the cooperative nature of most projects today. While an unclear document is being rewritten, a whole team of people can be waiting. Or, even worse, a team can start to work based on the information contained in an unclear document. Incorrect quantities of materials are purchased, construction begins in the wrong location, and so forth.
Unclear writing can also cause ethical problems. Ambiguous or confusing warnings on medication bottles and unclear instructions on how to operate equipment can cause sickness, injury, or even death. An unclear construction code can result in unsafe roads and buildings.
All the problems that can result from unclear writing can also be caused by inaccurate writing.
Accuracy is a simple concept in one sense: you must get your facts right. If you mean to write 2,000, don't write 20,000. If you want to refer to Figure 3-1, don't refer to Figure 1-3. Inaccuracies are at least annoying and confusing; they can also be dangerous, of course.
In another sense, however, accuracy is more complex. Workplace writing must be as objective and unbiased as you can make it. If your readers suspect you are slanting the information-by overstating or omitting a particular point-you will lose your credibility, and they might not believe anything you say.
The document should include all the information the readers need (or at least cross reference other necessary documents). An effective document includes a background section if the audience includes readers unfamiliar with the project. An effective document also includes a clear description of the writer's methods, as well as a complete statement of the principal findings-the results and any conclusions and recommendations.
Comprehensiveness is crucial for two reasons. First, the people who will act on the document need a complete discussion in order to apply the information safely, effectively, and efficiently. Second, the document functions as the official record of the project from start to finish.
For example, a scientific article reporting on an experiment comparing the reaction of a virus to two different medications will be published only if the writer has explained his or her methods in detail; other scientists might want to replicate the experiment. Or consider a report recommending that a company enter a new product area. Before committing itself to the project, the company will want to study the recommendation carefully. The people charged with this responsibility need all the details. And if the company decides to go ahead with the project, the report will serve as the official documentation for the project. Months or years later, company officials will know where to turn to find out what was done and why.
Excerpted from Writing in the Technical Fields by Mike Markel Excerpted by permission.
All rights reserved. No part of this excerpt may be reproduced or reprinted without permission in writing from the publisher.
Excerpts are provided by Dial-A-Book Inc. solely for the personal use of visitors to this web site.
Part I: Techniques 1
Chapter I. Introduction 3
Treat Workplace Writing as a Craft, Not an Art 3
Unlearn What You Learned in School 4
Focus on What You Know About Writing at Work 6
Characteristics of Effective Workplace Writing 7
Chapter 2 Before You Start Writing 13
Use Short Writing Sessions, Not Long Ones 13
Write Collaboratively 15
Analyze Your Audience 17
Define Your Purpose 18
Evaluate the Implications of Your Audience and Purpose 19
Make Sure Your Boss Agrees with What You've Decided 21
Chapter 3. Understanding the Writing Process 23
Generate Ideas to Include in the Document 23
Organize Your Information 26
Write the Draft Quickly 34
Spend Your Time Revising 34
Chapter 4 Using the Computer to Improve Your Writing 39
Understand What the Computer Can—and Cannot—Do for You 40
Use the Computer When You're Just Getting Started on a Document 40
Use the Computer When You're Drafting 41
Use the Computer When You're Revising 42
Use Specialized Software 43
Chapter 5. Improving the Coherence of Your Writing 47
Write Informative Titles and Headings 48
Use Lists to Communicate Parallel Information 50
Use Introductions to Forecast Discussions 52
Use Conclusions to Complete Discussions 55
Chapter 6 Writing Better Paragraphs 59
Begin with a Clear Topic Sentence 59
Support the Topic Sentence Logically 61
Emphasize the Coherence of the Paragraph 62
Keep Paragraphs to a Manageable Length 65
Chapter 7. Writing Better Sentences 67
Determine the Appropriate Stylistic Guidelines 68
Use the Active and Passive Voices Appropriately 68
Choose Appropriate Sentence Patterns 70
Focus on the Real Subject 72
Focus on the Real Verb 73
Use Modifying Elements Effectively 74
Keep Parallel Items Parallel 76
Chapter 8 Choosing the Right Word 79
Choose Simple, Clear Words and Phrases 79
Avoid Unnecessary Jargon 82
Avoid Euphemisms 82
Avoid Cliches 82
Avoid Sexist Language 83
Use Readability Formulas Carefully 84
Chapter 9 Creating and Integrating Graphics 87
Determine Whether You Need Graphics 87
Determine What Kind of Graphic to Use 89
Make the Graphic Honest 90
Make the Graphic Self-Sufficient 91
Determine Where to Put the Graphic 95
Tie the Graphic to the Text 95
Chapter 10. Improving Page Design 99
Leave Adequate Margins 100
Consider a Multicolumn Format 101
Use Appropriate Line Spacing 102
Use Appropriate Justification 104
Understand the Readability Levels of Type Fonts 106
Use the Different Members of a Type Family 107
Use Type Sizes Appropriately 108
Use Uppercase and Lowercase 110
Design Titles and Headings for Emphasis and Clarity 110
Design Lists for Clarity 112
Part II: Applications 115
Chapter 11. Letters 117
Learn the Standard Letter Formats 117
Learn Letter Protocol 118
Forecast the Purpose of the Letter 122
End on a Positive Note 123
Achieve a Natural Tone 124
Chapter 12 Memos 127
Create an Informative Heading 128
State the Purpose Up Front 128
Include a Summary 129
Conclude with an Action Statement 130
Chapter 13. Minutes 135
Include the Necessary Housekeeping Details 136
Record Events Accurately 136
Record Events Diplomatically 137
Chapter 14 Procedures and Manuals 141
Emphasize Safety 142
Orient the Reader 145
Write Clear Instructions 148
Add Graphics to Clarify the Text 150
Design the Document for Easy Use in the Field 152
Anticipate the Need for Updates 154
Include Troubleshooting Tips 154
Chapter 15. Formal Elements of Reports 157
Transmittal Letter 158
Title Page 160
Table of Contents 160
Executive Summary 164
Chapter 16 Proposals I69
Plan Before You Start Writing 170
Show That You Understand the Readers’ Needs 171
Propose a Clear, Specific Technical Plan for the Project 174
Demonstrate Your Professionalism and Credibility 176
Use Graphics to Help Your Readers See Your Ideas 177
Evaluate the Proposal Carefully Before You Send It Out 178
Chapter 17. Progress Reports 183
Clarify the Context 183
Explain the Progress Clearly 184
Explain the Progress Honestly 185
Chapter 18. Completion Reports 189
Introduce the Report Clearly 190
Describe Your Methods 191
Present Your Results 192
Draw Conclusions from the Results 194
Present Your Recommendations 195
A. Checklists 199
B. Handbook 207
C. Commonly Misused Words and Phrases 241
D. Guidelines for Speakers of English as a Second Language 247
E. Guidelines for Writing to Speakers of English as a Second Language 261
F. Selected Bibliography 265