Effective Writing A reference manual to assist anyone who needs to write documents in the workplace. by Frank ‘Choco’ Munday Hot Rod Handbooks 2 Effective Writing Table of Contents CHAPTER 1 Writing at Work 9 References and Recommended Reading 9 About the Author 10 Technical Communication 11 Writing at Work versus Writing at School 11 CHAPTER 2 Occupational Health and Safety 13 What Are The Risks? 13 How Can The Risks Be Controlled? 14 CHAPTER 3 Rules of Grammar 15 Sentence Structure 15 Parallel Construction 19 Positive, Comparative and Superlative Adjectives and Adverbs 20 General Use of Commas 21 Conjunctions 21 Comma Splice 21 Introductory Statements 21 Between Items in a Series 22 Within Transitions 22 To Enclose a non-Essential Phrase 22 Beginning Introduction 23 Indicate Possession 24 Join Clauses 24 Integrate a Quote 24 Colons and Semi Colons 25 Apostrophe Abuse 26 An Apostrophe Denotes Missing Letters 26 An Apostrophe Denotes Possession 26 An Apostrophe NEVER Denotes Plurals 26 The Importance of Correct Punctuation 27 Adding Emphasis 28 Punctuation Marks for Achieving Emphasis 29 Quotation marks as Emphasis 29 Numbers and Numbering 29 Exceptions to the Numbering Rule 29 Non-abbreviated Units 30 Abbreviated units 30 Metric Prefixes 31 Spaces with units 31 Some More Guidelines when Working With Units and Num- bers 31 Numerical Values in Sentences 32 Double Numbering 32 Hyphens 33 The Other Hyphens 35 Doubling of Last the Letter 36 CHAPTER 4 Getting Started 39 Start at the Beginning 39 Evaluate the Aim of your Document 40 Effective Writing 3 Document Type 41 Document Planning 43 Outline 44 Use Strong Headings 45 Title Case 45 Dump Non-essential Information 45 Use Distinct Headings 46 Use Headings to Group Lists 46 Avoid Heading and Paragraph Numbering 48 Your Audience 51 Match Content to Your Audience 52 Use You and We 53 CHAPTER 5 Document Structure 55 Placement of the Topic Sentence 57 Supporting a Topic Sentence with Details 57 New Paragraph 57 Use Examples, Tables and Illustrations 57 The First Page 59 Use of Fireworks 61 Use of Fireworks 61 CHAPTER 6 Write in Plain English 63 Before: 63 After: 64 Before: 64 After: 64 Plain English Writing Techniques 65 Fuzzy Meanings 67 Omit unnecessary words 68 Accentuate the positive 70 Double Negatives 70 Exceptions to the rule 71 Famous double negatives: 71 Active Voice 72 Going from Passive to Active 72 Passive to Active: Who-Does-What 73 When to use Passive Voice 74 Using a List to Shorten Sentences 75 Making difficult text simple 77 Analogies, Examples, Comparisons 78 Graphics 79 An Exercise in Illustrations 80 Illustration: 81 Tables 81 CHAPTER 7 Avoid Confusing or Ambiguous Text 83 Abstract Words and Phrases 83 Redundancies 85 Things to think about.... 85 Avoid the Word ‘Please’ 86 Jargon 86 Email Jargon that is sometimes used in Help and Technical Documents 88 Don’t Overuse Technical Terms 88 Avoid Legal Jargon 88 4 Effective Writing Officious and Flowery Language (“Cop Speak”) 90 Acronyms and Abbreviations 95 Business Acronyms to Avoid 97 Latin (and French) 99 Clichés 103 Repetition 105 Sexist Language 105 Misplaced Modifiers 106 Mixing American, Australian and British English 109 Archaic Words and Phrases 110 CHAPTER 8 Poor English 113 Poor Word Usage 113 Dangling comparatives and superlatives 114 Verbalised Nouns 114 Prepositions Placement 114 Eggcorns 117 Mixed Metaphors 118 Common Misuse of Words 121 Frequently Misspelled Words 144 CHAPTER 9 Bad Writing Habits 145 Un-words 145 Some un-words that seem to have made it into Technical Writing 149 Americanised Words 149 Is Americanisation of Australian English a Real Threat? 150 Weasel Words 153 Dangerous Weasel Words 154 Weasel Word Job Titles 157 CHAPTER 10 Memo Writing 159 Memo Segments 159 Heading Segment 160 Opening Segment 160 The Problem 160 The Task 160 The Purpose 161 Summary Segment 161 Discussion Segments 161 Closing Segment 161 Necessary Attachments 162 Case Study: The Importance of Effective Memo Writing 163 Conclusion 164 Excerpt from the report into the disaster: 164 Meeting Agenda and Minute Writing 165 Agenda Format 165 Minutes Template 165 Style Guide for Meeting Minutes 166 Effective Writing 5 CHAPTER 11 Procedure Writing 167 Planning a Procedure Document 167 Sections of a Procedure Document 168 The First Step 169 Get To The Point 169 Types of Steps 169 CHAPTER 12 Business Letter 173 Date 173 Sender’s Address 173 Recipient’s Address 173 Salutation 174 Body 174 Closing 174 Enclosures 174 Typist initials 174 A note about format and font 174 CHAPTER 13 Document Review 177 Peer Review Checklist 177 Some points on peer-reviewing someone’s work: 178 Why Reviewing is Important 178 CHAPTER 14 How NOT To Write 181 The Longest Sentence in the World 183 Oldies but Goodies 183 Terrible Analogies 185 English Language Ambiguities 186 THE PHAOMNNEAL PWEOR OF THE HMUAN MNID 187 The Final Fixing of the Foolish Fugitive 187 CHAPTER 15 Writing For Developers 193 Error Messages, Prompts and Warnings 193 A Good Error Message 197 Error Message Writing Techniques 198 Review Messages 203 CHAPTER 16 Quiz 205 Negative to Positive 205 Active vs Passive 205 Get to the Point 206 Sentence Length 207 Who-Does-What 207 Simplifying Complex Words 208 Complex to Simple 208 Unwords 210 Misplaced Modifiers 211 Parallel Construction 211 Wasted Words and Unnecessary Words 212 Apostrophe Abuse 212 Colons 213 Poor English 214 Egg Corns 214 6 Effective Writing Procedure Writing Exercise – Video Recorder 215 Effective Writing Quiz Solutions 217 Negative to Positive 217 Active vs Passive 217 Sentence Length 218 Who-Does-What 218 Simplifying Complex Words 218 Complex to Simple 219 220 Unwords 220 Misplaced Modifiers 220 Parallel Construction 220 Wasted Words and Unnecessary Words 221 Apostrophe Abuse 221 Colons 222 Poor English 222 Egg Corns 222 Video Recorder Exercise Possible solution 223 Effective Writing 7 8 Effective Writing CHAPTER 1 Writing at Work Writing is a skill that needs to be developed by anyone who produces documents for work. From memos to Technical Manuals, an author of a document needs to com- municate information to others in a format that can be easily understood and free from ambiguity. Poorly written documents mean that your audience, whoever they may be, will not get the message clearly. Studying this document won’t make you into a Technical Writer. It will, however, provide a ready reference and a basis from which you can develop the ability to rec- ognise good writing practices. Embracing these simple practices will improve the part of your skill set that requires you to write effectively in the workplace. References and Recommended Reading Style Manual for Authors, Editors and Printers, Sixth Edition. http://www.agimo.gov.au/information/publishing/style_manual Microsoft Manual of Style for Technical Publications Plain English at Work http://www.dest.gov.au/archive/publications/plain_en/homepage.htm The Macquarie File Writers Guide http://catalogue.nla.gov.au/Record/2082520 Plain English Manual (Office of Parliamentary Counsel) http://www.opc.gov.au/about/docs/pem.pdf Common Errors in English Language, by Paul Brian http://www.wsu.edu/~brians/errors/ Effective Writing 9 Writing at Work About the Author Frank ‘Choco’ Munday has developed and presented courses on Technical Writ- ing, Effective Writing, Writing for Software Developers, to name a few, as a sort of a sideline to a Technical Writing/Training career that started in the late 80s. The need for reference material for the training courses has resulted in the production of this manual, but has been re-formatted as a stand-alone Reference Manual for Effective Writing in the Workplace. Much of the subject matter has been presented at conferences, such as those hosted by the AODC and ASTC. The courses have been configured and re-configured many times, depending on the audience and the subject matter. Here’s just a sample of some of the feedback received by participants of Choco’s writing courses: 10 Effective Writing Technical Communication Choco spent 20 years in the Royal Australian Navy as an Electronic Technician, specialising in digital cypher technology, radio communications and high power transmitters. He was surprised to discover that his penchant for writing could earn him a job as a Technical Writer for a ship design company once he left the Navy behind. That was 1990, and it launched a new career, first in the Defence Electron- ics industry, then in Government and the public sector. In between contracts, Choco wrote several technical manuals on the topics of automotive engine management systems, electronic fuel injection and auto electronics in general. Technical Communication Why is it important to communicate effectively? The following is an extract from an explanation document for GST written by the Australian Treasury department. It was published in an effort to explain some aspects of the GST to the wider popu- lation: “Financial products supplied by a financial supply facilitator are not financial supplies. However, a supply of an interest facilitated by a finan- cial supply facilitator is a financial supply by the financial supply provider if the supply of the interest is one to which regulation 40-13 applies”. If you understood that, then perhaps this book is not for you. For most people, the author of this extract failed to communicate the meaning to the intended audience. The field of technical communication is a professional field with degree programs, certifications, and theory. However, the focus for this book is not as an incentive for you to embark on a career as a technical writer, but an introduction to the kinds of writing skills you need in professional work. No matter what sort of professional work you do, you are going to be required to do lots of writing, most of it technical in nature.