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 communicate 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 recognise 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 population: “Financial products supplied by a financial supply facilitator are not financial supplies. However, a supply of an interest facilitated by a financial 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. The more you know about some basic writing skills, which are covered in this document, the better job you will do in communicating with the people who read your documents. That can only be good for the projects you work on, for the organisations you work in, and for you and your career.

Writing at Work versus Writing at School

We are taught to write in school, and we take that basic education with us into the workforce. However, there are several differences in the way we were taught to write in school, and the way that we use written communication in the workforce. • Writing at work achieves job goals. • Writing at work addresses a variety of readers. • Writing at work addresses readers with different perspectives. • Writing at work creates excessive paperwork and email.

In the workforce, the reader will ask: • What is this? • Why should I read this? • How does it affect me? • What am I going to have to do? • Writing at work may be read by readers unknown to the writer.

Effective Writing 11 Writing at Work

• Writing at work has an indefinite life span. • Writing at work creates legal liability for the writer and the organization. • Writing at work uses a variety of written documents.

Some People Struggle to Read

People struggle to read for many reasons, but most authors in the workplace are unaware of this. Writing at work means that authors must consider the possibility that some readers may fall into one or more of the following categories: • Physical impairments. Partial blindness, glaucoma, and colour-blindness can cause problems for people when they read. • Cognitive impairments. Autism, dyslexia, and learning disabilities. Cognitive impairments are not always permanent, and are not always serious. For example, a person who needs to look at a user guide is angry or frustrated, and has a headache. That mental state decreases the cognitive ability of the reader. • Low literacy. Many adults have a reading level at or below 13-14 year old children. • English is a Second Language. More and more often in the workplace, your audience may comprise people who use English as their second language. • Poor Document Structure and Style. Unstructured and poorly laid out documents are hard to read. Styles like legalese, 'small print', or any document with physically tiny print (like medicine labels) are also difficult to follow and absorb. • Aging. Aging decreases capabilities that affect reading. For example, vision impairment becomes more common in old age. Additionally, some older people have less experience with technical language. Even relatively common IT terms such as 'desktop', 'pointer' and 'mouse' can be obscure.

12 Effective Writing CHAPTER 2 Occupational Health and Safety

It is your responsibility to ensure that the risks associated with the use of computers is effectively controlled, specifically: • Posture • Eyes Strain

What Are The Risks?

Prolonged work with computer monitors may give rise to visual fatigue (eye strain). Some of the symptoms of eyestrain are: • headache; • burning or itching eyes; • double vision or blurring; • nausea; or • fatigue.

Incorrect positioning of the computer monitor or of the worker can lead to: • sore back, neck and shoulders; • sore hands and wrists; or • occupational overuse syndrome (OOS).

Effective Writing 13 Occupational Health and Safety

How Can The Risks Be Controlled? • Position the monitor at right angles to the window at a distance of 45 - 65 cm from the eyes and make sure that artificial lighting does not reflect from the screen;

• Close, or partly close, the blinds and eliminate all reflective surfaces near the computer monitor; • Position the top of the screen at eye level and adjust the height of the keyboard so that your arms hang freely, with the keyboard at a slight angle; • Keep your wrists in a straight line with your forearms; • Take periodic breaks to give hands a brief rest (10 minutes every hour is recommended); • Keep your spine and head upright and sit well back in your chair. The chair should support the natural curvature of your back and the height of the chair should be adjustable. A chair that curves down in front will reduce harmful pressure on the back of the knees. A chair that adjusts forward and backwards will provide more flexibility for the back. • Keep your feet flat on the floor and use your thighs to help support your body weight; • Keep your knees at the same level as your hips and use a foot rest if necessary;

For more information, refer to Officewise: A guide to health and safety in the office (OHS 1) on the Comcare web site.

14 Effective Writing CHAPTER 3 Rules of Grammar

“In this digital age, when we communicate increasingly in written texts and posts, your words are all you have.” Kyle Wiens, CEO of iFixit, an online repair manual.

Maintaining commonly accepted standards of grammar ensures your documents are understood by everyone. The following are some basic rules that should remove any ambiguity when writing or editing documents. • Sentence Structure, including: • Run On Sentences • Sentence fragments • Tense shifts • Person shifts • Split infinitives • Parallel Construction • General Use of Commas (including colons and semi-colons) • Apostrophe Abuse • Adding Emphasis • Numbers and Numbering • Hyphens • Doubling of Last the Letter

Sentence Structure

A sentence is a group of words that forms a complete meaning: that is, the words can stand by themselves and still make sense. A sentence: • begins with a capital letter and ends with a full stop or question mark. • consists of a subject, a verb, and an object.

For example:

Effective Writing 15 Rules of Grammar

The Police Officer (subject) arrested (verb) the offender (object).

This is a basic sentence, and it would not be good style to write all of your sentences as simply as this. To add extra information about the main elements of the sentence, we include relative clauses and phrases: The Police Officer, responding to a complaint, arrested the offender who sur- rendered peacefully.

Run On Sentences

There are two types of run-on sentence. The most obvious is one in which two (or more) sentences are run together with no punctuation at all between them. Another far more common type occurs when two sentences are joined by a comma, instead of being separated by a full stop. Run-on sentence: Students who do poorly are told to pay attention what 'paying attention' means is never properly examined. Correct versions: Students who do poorly are told to pay attention. What 'paying attention' means is never properly examined. Students who do poorly are told to pay attention, but what 'paying attention' means is never properly examined.

You can also correct this error by joining the sentences with a semi-colon (;), or by placing an appropriate connecting word such as 'and', 'but' or 'because' in front of the second sentence.

Sentence fragments

A sentence fragment is a group of words that does not form a complete sentence. For example: Although it was raining.

Despite the fact that “Although it was raining” begins with a capital letter and ends with a full stop, it is really just a sentence fragment because it does not make sense by itself.

To correct the problem, the fragment must be attached to a complete sentence that gives it a context: Although it was raining, we went for a drive.

Sentence fragment (the fragment is in bold text): Maslow's 'Hierarchy of Needs' theory has influenced research in the fields of psychology and education. Although his original theory has now been modified. Correction: Maslow's 'Hierarchy of Needs' theory has influenced research in the fields of psychology and education, although his original theory has now been modified.

Tense

English has a number of tenses, which refer to the time at which a verb action occurred, and moods, which signal whether the verb action is being described, commanded or expressed conditionally. When writing a sentence, you need to keep

16 Effective Writing Sentence Structure

your tenses and moods consistent throughout. This can become difficult as a sentence becomes longer and contains more clauses.

The following sentence is expressed in the past tense - it refers to something that has already happened: When I was walking by the lake, looking for my dog, I saw Justice Kirby practising his tai chi.

NOT When I was walking by the lake, and I am looking for my dog, I see Justice Kirby practising his tai chi.

“Am looking” and “see” indicate the present tense - something happening now. Some people make the mistake of using the passive form of saw, seen in this sentence. But ‘seen’ should be used like this: Justice Kirby was seen practising his tai chi by the lake by the woman looking for her dog.

The following sentence is expressed in the future tense: I won't be able to help you, even if you become a student in the Faculty, as I will be working as a belly dancer next year.

NOT I won't be able to help you, even if you become a student in the Faculty, as I am working as a belly dancer next year.

Again, “am working” indicates the present tense, not the future tense.

Person

Avoid shifts in person and number. Use first, second or third person in the singular or plural form consistently throughout your document.

TABLE 1. Person

Singular Plural IWe First Person You You Second Person He or She They Third Person

For example: Mixed person From the Case Log, you can edit log entries provided users have access permissions. If you do not have write access for the log entry, the log entry is shown in view-only mode. For full access, they should contact a coordinator. Second person From the Case Log, you can edit log entries provided you have access permissions. If you do not have write access for the log entry, the log entry is shown in view-only mode. For full access, contact your coordinator.

Effective Writing 17 Rules of Grammar

Split infinitives

These are common, but simple to avoid. The infinitive form of the verb is its simple form: to eat, rather than eating, eaten. to run, rather than running, ran. to prevaricate, rather than prevaricating, prevaricated.

If you add an adverb (a word ending in `-ly' which describes the way in which the verb action is performed), you should avoid putting the adverb in the middle of the verb:

Correct: He tried to eat hastily.

Split He tried to hastily eat.

Correct Slowly she began to run away from him.

Split She began to slowly run away from him

Correct He was known constantly to prevaricate.

Split He was known to constantly prevaricate

There is no grammatical rule that states that you should never split an infinitive. It became a rule among some literates to remove ambiguity or to create a standard. Most writers disagree, and there are plenty of examples to support this.

The only rule that counts is clarity. If splitting the infinitive makes the sentence less awkward, go ahead and split it. If not splitting it changes your meaning, then split it. For example: Haley decided to quickly remove Jason's toys.

The split infinitive is “to quickly remove,” but if you move the adverb “quickly” before the infinitive, you imply that Haley made the decision quickly. Haley decided quickly to remove Jason's toys.

This is the safest “official” rule: “Don’t split an infinitive if you don’t have to.”

18 Effective Writing Parallel Construction

Parallel Construction

Parallel construction makes a strong point and creates a smooth flow by combining two or more ideas or attributes in a single sentence. There are two rules of Parallel Construction: • Persistent Prepositions/articles. If the preposition or article (a, an, the) is the same for all items in a list, the writer can decide to include them in all of the items or write it just in the first. • Persistent Grammatical Form. The words in the list must be of the same grammatical form, that is, all nouns, all infinitives, or all clauses.

The prepositions or art icles must be consistent. For example: Incorrect: Paula went to work, a restaurant, and to the movies.

The items in the list in the example above are work, a restaurant, and the movies. However, the writer used the preposition to with the first and third items only. Correct: Paula went to work, a restaurant, and the movies. Correct: Paula went to work, to a restaurant, and to the movies.

The words in the list must have a persistent grammatical form, that is, all nouns, all infinitives, or all clauses. When used incorrectly, the sentence sounds wrong: Incorrect: I find surfing more pleasurable than to ski. Correct: I find surfing more pleasurable than skiing.

Keep the form of the verb consistent: Incorrect: We employ people to write programs and interviewing clients is also necessary.

The verbs are write and interviewing. The forms are different. Correct: We employ people to write programs and interview clients.

Choose whichever form you like, but be consistent: Incorrect: We are interested in hearing your ideas on motivating employees, how to introduce change, and quality control techniques. Correct: We are interested in hearing your ideas on motivating employees, introducing change, and controlling quality. Correct: We are interested in how to motivate employees, introduce change, and control quality.

This rule stands for all lists, for example the following two lists describe actions that can take place in a dialogue box in a computer application:

Correct (consistent) Incorrect • enter property data • enter property data • delete property data • delete property data • print • printing • exit • exiting • cancel • cancelling • choose an end date • choose an end date

Effective Writing 19 Rules of Grammar

Positive, Comparative and Superlative Adjectives and Adverbs

There are three types of adjectives: Positive, Comparative, and Superlative.

Comparatives are forms of adjectives or adverbs used to compare two different things. With adjectives you add er to the end to make a comparative. If the adjective ends in y, drop the y and add ier. For example:

TABLE 2. Adjective Comparative

Adjective Comparative tall taller easy easier

For adverbs, we use more or less to prefix the positive to form the comparative. For example”

TABLE 3. Adverb Comparatives

Adverb Comparative quickly more quickly softly more softly Superlatives are forms of adjectives or adverbs used to compare three different things.

TABLE 4. Adjective Superlatives

Adjective Superlative better best worse worst

The following table summarises the forming rules of Comparatives and Superla- tives:

TABLE 5. Forming Comparatives and Superlatives

Descriptive Example of Adjective Type Comparative Superlative One Syllable strong add " er" add "est" adjectives stronger strongest More Than One famous add "less" or "more" add "most" or "least" Syllable more famous least famous Expensive Comfortable Dangerous Boring

20 Effective Writing General Use of Commas

TABLE 5. Forming Comparatives and Superlatives More Than One silly remove "y" add "ier" remove "y" add "iest" Syllable Ending sillier silliest "y" for less for least less silly least silly Happy Funny Irregular bad worse worst good better best much/many more most few/little less least

General Use of Commas

Comma abuse has reached epidemic proportions in recent years. A misplaced or missing comma can change the entire meaning of a sentence or a paragraph, and is the most powerful punctuation mark in the English language. Therefore, it should be treated with respect. What follows are the rules for comma usage that should be committed to memory.

Conjunctions

Use a Comma before a coordinating conjunction (but, and, or, nor, for, so, yet) to join independent clauses (clauses that could be sentences on their own). You can avoid hard-to-read sentences this way: confusing: All small boats must return to port immediately or they may sink in the hurricane that is approaching the bay. improved: All small boats must return to port immediately, or they may sink in the hurricane that is approaching the bay.

Comma Splice

If you used a comma, but omitted the conjunction “or,” you have a “comma splice.” Don't do this. Never connect two complete sentences with a comma alone. comma splice: All small boats must return to port immediately, they may sink in the hurricane that is approaching the bay. correct (with semicolon): All small boats must return to port immediately; they may sink in the hurricane that is approaching the bay.

Introductory Statements

Use a comma after a short introductory statement:

Effective Writing 21 Rules of Grammar

unclear: While we were driving a cat crossed the road. (What were you driving? A cat?) clear: While we were driving, a cat crossed the road. Unclear: When it comes to eating people differ in their tastes. Clear: When it comes to eating, people differ in their tastes. Babble: You use the Filter button to filter the log objects currently shown reducing the number of entries displayed. Babble repaired: You use the Filter button to filter the log objects currently shown, reducing the number of entries displayed.

Between Items in a Series

Use a comma between items in a series: “PROMIS is the sole means used to record referrals for AFP action or investigative activity from client agencies, law enforcement bodies, other organisations, or members of the public.”.

Exceptions: when the last two items in a series are closely related, you may omit the comma. The guards brought the prisoner a meal of steak, potatoes, bread and butter.

This rule is controversial, because some grammar books (and professors) will state that the comma must always be used to avoid confusion. In these examples, the issue is not so clear: The patients sued the insurance company, the hospital and the doctors. The injured parties sued the insurance company, the hospital, and the doctors.

Were two or three parties being sued? This is where the grammatical rule becomes difficult.

Within Transitions

Use a comma before and after some transitional words. This class is, incidentally, only offered at night. For example, we have to pay the light bill. He was, moreover, completely unprepared for the test. Nevertheless, we all got in trouble. To Separate Quotations

Use a Comma to set off quotations from their introductions or closes. Note that a final comma goes inside the closing quotation mark. “All's well that ends well,” wrote Shakespeare. As Shakespeare put it, “All's well that ends well.”

To Enclose a non-Essential Phrase

Use commas to enclose non-restrictive clauses or phrases, which are not essential to the sentence's meaning.

22 Effective Writing General Use of Commas

The student, in his new BMW, drove into the lake. (the type of car just gives us more information). The party went on all night, although many guests left quite early. However: The company wanted an employee who had a lot of computer experience to manage the new system. (The part stating “who had a lot of computer experience” is essential here).

DO NOT USE a Comma to bracket phrases that are essential to a sentence's meaning. If removing the information would drastically change the sentence's meaning, then that information is essential and would not be set off by commas. For example: Incorrect: The bus driver with her ears tuned to the roar decided to take the grumbling bus on a detour across the football field. Correct: The bus driver, her ears tuned to the roar, decided to take the grumbling bus on a detour across the football field. Incorrect: My window as dirty as it is reveals the beauty of nature on a snowy morning. Correct: My window, as dirty as it is, reveals the beauty of nature on a snowy morning. Incorrect: King and Lucille, his customized black Gibson have electrified audiences all over the world. Correct: King and Lucille, his customized black Gibson, have electrified audiences all over the world. Incorrect: The man, who has too many ties, has too few necks. Correct: The man who has too many ties has too few necks. Incorrect: The cats, with six toes, are a unique attraction of the tour of Hemingway's house. Correct: The cats with six toes are a unique attraction of the tour of Hemingway's house. Incorrect: Only entities, which you have access to, are included in the Case Report. Correct: Only entities which you have access to are included in the Case Report. Incorrect: Any member, who has access to the Case Log, can change the status of a case. Correct: Any member who has access to the Case Log can change the status of a case.

Beginning Introduction

Use a Comma when beginning a sentence with an introductory phrase or an introductory (dependent) clause. Incorrect: After buying the five pound jar of marshmallow spread he set off in search of a bulk portion of peanut butter. Correct: After buying the five pound jar of marshmallow spread, he set off in search of a bulk portion of peanut butter. Incorrect: With this he bestows the responsibility of his own happiness on his mother and father. Correct: With this, he bestows the responsibility of his own happiness on his mother and father.

Effective Writing 23 Rules of Grammar

Incorrect: As she begins to gain independence it is natural for Grete to regard the idea of dependency as repugnant. Correct: As she begins to gain independence, it is natural for Grete to regard the idea of dependency as repugnant.

Indicate Possession

Use a Comma to indicate possession. End a singular noun with an apostrophe followed by an “s”. Otherwise, the noun's form seems plural. Incorrect: Though the lobsters claws were bound, the creature made a threatening gesture as they dropped it in the pot. Correct: Though the lobster's claws were bound, the creature made a threatening gesture as they dropped it in the pot. Incorrect: In a democracy, anyones vote counts as much as mine. Correct: In a democracy, anyone's vote counts as much as mine. Incorrect: There is a vast age difference between Victors mother and father. Correct: There is a vast age difference between Victor's mother and father.

Join Clauses

Use a Comma to join two independent clauses. Use a comma followed by a conjunction, a semicolon alone, or a semicolon followed by a sentence modifier. Incorrect: The delivery boy knew he carried strange cargo, but still ventured off unafraid. Correct: The delivery boy knew he carried strange cargo, but he still ventured off unafraid. Incorrect: My math teacher doesn't know how to lecture, she should have remained a student. Correct: My math teacher doesn't know how to lecture; she should have remained a student. Incorrect: Gregor has not changed physically; but has given himself an excuse to separate himself from the pain of previous experiences. Correct: Gregor has not changed physically; however, he has given himself an excuse to hide from the pain of previous experiences.

Note: Be careful that you make the subject and verb agree with each other, not with a word that comes between them.

Incorrect: The gourmet dinner, right down to the beautiful centrepiece, were devoured by the escaped dingo. Correct: The gourmet dinner, right down to the beautiful centrepiece, was devoured by the escaped dingo. Incorrect: The cart, as well as its contents, were gone. Correct: The cart, as well as its contents, was gone. Incorrect: The girl, along with her classmates, like the new teacher. Correct: The girl, along with her classmates, likes the new teacher.

Integrate a Quote

Use proper punctuation to integrate a quotation into a sentence.

24 Effective Writing General Use of Commas

Note: Commas (and periods) ALWAYS stay inside quotation marks!

Incorrect: Tumbling down the hill, Jack yelled: “Gosh, I'm sick of this.” Correct: Tumbling down the hill, Jack yelled, “Gosh, I'm sick of this.” Incorrect: Her letter spoke to him in harsh tones, “You never fail to repulse me.” Correct: Her letter spoke to him in harsh tones: “You never fail to repulse me.” Incorrect: He views the problem as a slight delay or a sickness that will eventually disappear, “I will go back to sleep for a few minutes and forget all this nonsense.” Correct: He views the problem as a slight delay or a sickness that will eventually disappear: “I will go back to sleep for a few minutes and forget all this nonsense.”

Colons and Semi Colons

Colons and semi colons are punctuation marks that have lost much of their credibility, and many writers use them incorrectly. The rules for colons and semi colons can be broadly explained as follows: • A colon connects what precedes something with what follows. • A semi colon separates what precedes it with what follows.

The colon is often used to introduce a list of items. For example: You will need to bring three things to the party: some food, something to drink, and a small gift for the hostess. You can also use a colon to introduce an explanation or a definition of something. For instance: I'll tell you what I'm going to do: I'm going to quit! "Elephant (noun): a large grey mammal found in Africa and India."

The semi-colon is often used to join together two closely related, complete sentences, eliminating the need for a comma and coordinating conjunction (and, but, or, nor, for, so, yet) to join them. You must choose either to use a semicolon or to use the comma + coordinating conjunction set. A comma by itself constitutes a comma splice.

For example: Mary drives a Mercedes; Helen drives a Holden.

These two clauses could be separate sentences: "Mary drives a Mercedes. Helen drives a Holden." However, when we use a semi-colon, we are usually suggesting that there is a relationship between the sentences.

Use a semi-colon to join two clauses using a transition such as however, therefore, on the other hand. For example: in addition: She works all day in a store; in addition, she takes classes in the evenings. However: John is from Adelaide; however, he lives in the ACT. Otherwise: You should get your brakes fixed; otherwise, you might have an accident.

Effective Writing 25 Rules of Grammar

Therefore: Hundreds of people cross the border from the US to Canada every day; therefore, it is not possible to search all of them carefully.

Apostrophe Abuse

The rules concerning the use of Apostrophes in written English are very simple:

An Apostrophe Denotes Missing Letters

They are used to denote a missing letter or letters, for example: • I can't instead of I cannot • I don't instead of I do not • it's instead of it is

An Apostrophe Denotes Possession

They are used to denote possession, for example: • the dog's bone • the company's logo • Jones's bakery (but Joneses' bakery if owned by more than one Jones)

... but please note that the possessive form of it does not take an apostrophe any more than ours, yours or hers do • the bone is in its mouth

... however, if there are two or more dogs, companies or Joneses in our example, the apostrophe comes after the 's': • the dogs' bones • the companies' logos • Joneses' bakeries

An Apostrophe NEVER Denotes Plurals

Apostrophes are NEVER ever used to denote plurals! Common examples of such abuse (all seen in real life!) are: Incorrect: Banana's for sale Correct: Bananas for sale Incorrect: Menu's printed to order Correct: Menus printed to order Incorrect: 1000's of bargains here! Correct: 1000s of bargains here! Incorrect: New CD's just in! Correct: New CDs just in! Incorrect: Buy your Xmas tree's here! Correct: Buy your Xmas trees here!

Note: Special care must be taken over the use of your and you're as they sound the same but are used quite differently:

26 Effective Writing Apostrophe Abuse

• your is possessive as in this is your pen • you're is short for you are as in you're a propeller head

Separate and Joint Possessives

When writing about jointly owned objects, treat the two owners as a single unit (a couple) and put an apostrophe only after the last name: John and Jane’s villa Ben & Jerry’s ice cream

If you add more owners, you still use one apostrophe: Bob and Carol and Ted and Alice’s party.

If each person owns their own item, you must then give each owner an apostrophe: John’s and Jane’s cars (each of them separately owns a car).

If you replace one or both of the individuals’ names with a possessive pronoun, watch out for awkwardness and reword if necessary.

For example: • Awkward: my and the seller’s signatures Better: the seller’s and my signatures or the seller’s signature and mine • Awkward: their and our houses Better: their house and ours • Awkward: your and your wife’s passports Better: the passports for you and your wife

The Importance of Correct Punctuation

We examine two “Dear John” letters:

Version 1: Dear John, I want a man who knows what love is all about. You are generous, kind, thoughtful. People who are not like you admit to being useless and inferior. You have ruined me for other men. I yearn for you. I have no feelings whatsoever when we're apart. I can be forever happy; will you let me be yours? Gloria

Version 2: Dear John, I want a man who knows what love is. All about you are generous, kind, thoughtful people, who are not like you. Admit to being useless and inferior. You have ruined me. For other men, I yearn. For you, I have no feelings whatsoever. When we're apart, I can be forever happy. Will you let me be? Yours, Gloria

Effective Writing 27 Rules of Grammar

Adding Emphasis

Before computerised word processing and desktop publishing, we would begin with a type written manuscript that was sent to a print shop. There it would be prepared for publication and printed. To show emphasis, such as the title of a book, refer to a key word, or to indicate a foreign word or phrase, the writer would use underlining in the typescript. The typesetter at the print shop would substitute italic font for those words. Using a mark-up language similar to SGML and, later, XML, typesetters would substitute words surrounded by with bold face type,

for bold, 14pt type and for italics.
Using computers means that the writer has a wide variety of fonts and textual effects to add emphasis (italics), strong (bold), and a library of formatting styles that were once the domain of the typesetter.
Generally, italics is the preferred way to emphasize words or phrases: “Submit one, and only one, form to the ATO”.
When describing something, use italics to bring the reader’s attention to what the thing is called that you are describing: “From the Case Log, you can edit log entries provided you have access permissions.” while bold is reserved for actions and headings. “Select the required entry type and click OK.” Chapter 3 – Operating Instructions
In technical manuals, help manuals and specification documents, use emphasis when referring to a screen, window or pane in a computer application: Result: The New Alert dialogue box is displayed. The following screen is a sample of the Case Summary screen. You can enter additional details relevant to the incident location in the Remarks text box.
It is important to emphasise the exact text that appears as the label in the computer application, equipment, system or appliance to differentiate between the label and the description: Click Search to launch the Find Person/Find Organisation search wizard.
If the dialogue box in the application is labelled Incident Location, you should describe it as such: To enter an incident location, type in the text in the Incident Location text box.
Don’t Overdo It
Overuse of various emphatic devices like changes of font face and size, boldface, ALL-CAPITALS AND SMALL CAPS creates the impression of a writer relying on flashy effects instead of clear and precise writing to make a point.
Avoid using ALL-CAPITAL letters for emphasis; they are unnecessary and can cause writing to appear cluttered and loud. In email correspondence, the use of all-
28 Effective Writing Numbers and Numbering
caps throughout a message can create the unintended impression of shouting and is therefore discouraged. Use Title Case for labels, headings and names.
Punctuation Marks for Achieving Emphasis
Some punctuation marks prompt the reader to give a word or sentence more than usual emphasis. For example, a command with a period does not evoke the same emphatic response as the same command with an exclamation mark. Warning! Hint!
A dash or colon has more emphatic force than a comma: Storing a permanent record of the transaction is mandatory, so save it to the Records folder. Storing a permanent record of the transaction is mandatory - save it to the Records folder. Storing a permanent record of the transaction is mandatory: save it to the Records folder.
Quotation marks as Emphasis
Quotation marks have two main functions: to indicate the use of someone's exact words, and to display the titles of literary and artistic works, not to set off words and phrases for special emphasis. If no location details were recorded on CAD, the location text box displays No complainant's address entered in CAD.
On the 28th November, 2005, I made a statement that “no complainant’s address was entered in CAD”.
Numbers and Numbering
In general, single digit numbers (zero through nine) are spelled out, while numbers of two or more digits (10, 20th Century) use figures.
Exceptions to the Numbering Rule
There are several exceptions to this simple rule:
Two or more related numbers. Use figures for all numbers when there are num- bers of two or more digits for related quantities in the same sentence, such as “6 out of 10 dentists recommend”.
Preceding a unit of measurement. Always use figures when a unit of measure- ment follows (for example, 5A).
Approximate values are spelled out. Always spell approximate values. If the approximate value is followed by a unit, then the unit is not abbreviated. • about five years • two orders of magnitude • about four times larger • several kilovolts
Effective Writing 29 Rules of Grammar
• a few tens of megahertz • a few volts
Zero and Infinity
There is no such thing as zero or infinity when writing measurements in numbers. When tempted to claim that some value is “zero” or “unmeasurably small”, give an estimate of the smallest non-zero magnitude that could be detected. For example: “The voltage at the base should be less than 5mV“ This is better than trying to justify the “zero” or insignificant voltage reading. For numbers between -1 and +1, insert a zero to the left of the decimal point in order to avoid a “naked decimal point”. For example, use 0.47, not .47. The intent of this rule is to make it more difficult for the reader to overlook the decimal point.
Mathematical Operations
Use figures when mathematical operations are implied: • factor of 2 • 3×3 matrix
When a number is at the beginning of a sentence it is always spelled-out. If this rule produces a result that looks awkward, it may be better to rewrite the sentence to avoid starting with a number
Use of units with numbers
All numerical values that have dimensions must have their units specified. In gen- eral, the units must follow the numerical value every time. However, in a table of numbers, the units may be specified at the top of the column, provided all of the values have the same units. If there are two numbers in a phrase with the same units (for example, “frequency between 4 and 5 kHz”), then put the units after the second number.
Non-abbreviated Units
All units, including those that are named for a person, have a lower-case first letter when written out (not abbreviated). Thus, write “ohm, farad, coulomb, volt, ampere, hertz” for units.
Abbreviated units
Units that are named for a person have an upper-case first letter when abbreviated (12 V, 3 Amps, 100 Hz); all other units have a lower-case first letter (15 oz, 10 lb, 6 ft). Abbreviated Units also have the following rules in writing: • The same abbreviation is used for the singular and plural form of a unit. • A period is not placed after an abbreviated unit, unless it is at the end of the sen- tence. • The proper abbreviation for “second” is “s”, not “sec”.
A note on Scientific Units that are named after people:
Most scientific units are named after the people who, historically, were prominent in bringing the units into being. For example:
30 Effective Writing Numbers and Numbering
• Hertz (Hz): The hertz is named after the German physicist Heinrich Rudolf Hertz, who made important scientific contributions to electromagnetism. • Volt (V): Alessandro Volta developed the so-called Voltaic pile, a forerunner of the battery, which produced a steady electric current. • Amp (A): The ampere is an SI base unit, and is named after André-Marie Ampère, one of the main discoverers of electromagnetism. • Ohm (): Ohm, a German physicist, discovered the relation between voltage and current in a metallic conductor, expressed in Ohm's Law.
Metric Prefixes
Metric prefixes of 106 and upwards have an upper case abbreviation (400 Mb, 100 Gb). Metric prefixes that are less than 106 use a lower case abbreviation (100 ml, 10ms, 200 kb, 120 kHz).
Spaces with units
There should always be one blank space between a number and a unit: “5 kHz”, not “5kHz”
In modern word processors, the space between number and unit should be a non- breaking space, so the number will always appear on the same line as its unit.
Note: There is no space between the metric prefix and the base unit.
Some More Guidelines when Working With Units and Numbers
Watch out for expressions such as: The signal generator had a 15 kHz frequency.
Units of measurement (“kHz”) are nouns and can not be used to modify another noun (“frequency”). The proper phrasing is: The signal generator had a frequency of 15 kHz.
This type of problem often occurs when length or thickness is specified, as in: 6 cm long
The proper phrasing could be: 6 cm in length the length is 6 cm having a length of 6 cm
Avoid labelling the axis on a graph or a column in a table as, for example,
volts x 10-3
This is ambiguous: are the numbers to be multiplied by the reader, or has the multi- plication already been done?
Maybe the number 3 on the axis of the graph or in a column of text means 3000 V, which times 10-3 is just 3. In such a case, the author should have written 3 kV.
Effective Writing 31 Rules of Grammar
Maybe the number 3 on the axis of the graph or in a column of text means 0.003 V, which is 3 x 10-3. In such a case, the author should have written 3 mV.
In general, choose a metric prefix that will make the numerical value between 0.1 and 1000. However, the value of a parameter or a variable over the range of a few paragraphs or in a table should have the same metric prefix to allow easy compari- son of different values.
The proper abbreviations for “alternating current, direct current, and root-mean- square” are lower case “ac, dc, rms”. However, if the term appears in a title or as the first letter in a sentence, then the entire abbreviation is upper case: “AC, DC, RMS”.
Numerical Values in Sentences
Whenever possible, give numerical values in statements and avoid ambiguous words. For example (from an automotive article about the effect of Continuous Variable Transmissions (CVTs) in automobiles on fuel consumption): The CVT's highway mileage is slightly less than a manual's, but not much.
It would have been better to say: A car with a CVT consumes 102% of the kilometres per litre on the high- way compared to the same car with a manual transmission.
The improved sentence is longer because words were added to make the consump- tion of fuel refer, properly, to the automobile and not to the transmission; also “mileage” was expanded to the proper “kilometres per litre”.
Double Numbering
Avoid the practice of writing the number and repeating it in numerals in brackets. For example: Print seven (7) copies of the document.
This convention is no longer a best practice in legal drafting, where it originated. Like many legal drafting conventions, it is an arcane practice that has persisted long after its useful life. It originated in the days of handwritten contracts, where it would have been easy to fraudulently alter a numeral. Writing out the words was a fail-safe, and is why the convention is still supported for writing out cheques; because they are handwritten.
From Black's Law Dictionary: In today's world of document processing, it's no longer necessary, even dangerous, to use this convention in the workplace. If there is a discrep- ancy, the words control, and they are harder to proofread. For example: “one million dollars ($100,000).” The eye picks out the number, not the words, but the words control.
32 Effective Writing Hyphens
Hyphens
There are no firm rules regarding hyphen use, and dictionaries disagree with each other in many cases. As a general rule, hyphens are used when they help to avoid ambiguity.
Most compound adjectives are hyphenated when they immediately precede the noun that they modify: switched-mode power supply differential-mode current steady-state voltage or current well-known fact high-frequency behaviour low-pass filter odd-integer terms
Note that the same words used as a noun are not hyphenated: open-circuit voltage short-circuit current but: “The configuration was an open circuit.” (no hyphen here) first-aid kit, but: “You render first aid.” (no hyphen here) worst-case scenario, but: “Consider the worst case.” (no hyphen here) high-voltage supply low-voltage system
But write There was high voltage on the wires that were supposed to carry low volt- age.
Compound words containing numbers or “half-” are hyphenated: half-life half-width half-baked one-half three-electrode tube four-terminal capacitor
Effective Writing 33 Rules of Grammar
first-order approximation two-thirds (Most technical writers would say “2/3”, not “two-thirds”.) 8-bit digitizer
Adverbs ending in “-ly” do not form hyphenated phrases: highly competent person fully ionized gas
We generally hyphenate noun-plus-noun words to produce words with a different meaning: owner-driver city-state hocus-pocus analog-to-digital converter state-of-the-art blue-green algae but we generally don’t hyphenate adjective-plus-noun compounds: black market red tape free will
Compound adjectives (a word made up of two adjectives) or noun-plus-adjective words are usually hyphenated: bitter-sweet accident-prone re-hot colour-blind icy-cold disease-ridden all compounds formed with “-free” are hyphenated: divergence-free
One generally does not hyphenate words formed by prefixes (Preclude, uncoopera- tive, insubstantial) except: all compounds formed with “self-, all-, ex-, quasi-” are hyphenated: self-extinguishing all-inclusive ex-president
Use or delete hyphens to distinguish from homonyms (words spelt the same but with different meanings):
34 Effective Writing Hyphens
re-cover, re-solved (hyphenate when meaning “cover again, solve again”) un-ionized (hyphenate when meaning “not ionized”)
Use a hyphen when last letter of prefix is identical to first letter of following word: de-emphasise (not deemphasise) pre-eminent (not preeminent) re-enter (not reenter) non-negative (non nonnegative)
The combination of two vowels does not usually require a hyphen: prearrange reallocate triennial
When there is otherwise a repeating sequence of letters that is confusing or ugly, try using a hyphen: non-ionizing non-oscillatory photo-ionization re-reading
For example, “nonoscillatory” looks like “no no scillatory” when read quickly.
When the prefix or suffix is added to a name, symbol, or number, a hyphen is included: non-Newtonian physics Cd-free solder pre-1970 designs mid-1970s
Note that this rule says that the following have no hyphen: nonlinear coauthor metastable multiconductor semiconductor infrared LED
The Other Hyphens
Writing and publishing software (for example Word, Publisher, FrameMaker) pro- vide great features such as a spell checker, thesaurus and grammar tools, but they have their limitations. Watch out for automatic hyphenation. Proof read carefully!
Effective Writing 35 Rules of Grammar
Olive Pitt, the music teacher, believed that disco- very often leads to effective learning. The track star gained popularity through the new- sprint rather than jumping hurdles. The members of the House of Lords are tit- led gentlemen who keep abreast of things. The temperance movement suffered a bar- rage of verbal abuse and misunderstanding. Commercial promotions and ad- vice is where the money is. Martin Place asked his lawyer to read- just his fees on the new contract. The Psychiatric Institute provides the- rapists for private consultations. The Trade Council knew that to un- ionize the electrical workers would cause static. Lucy Turnbull insisted she would beg- in her campaign for mayor. Incompetence can be found now- here in this organisation.
Doubling of Last the Letter
General rule: The rule for words which end with a single consonant is to double the last letter: • Chat: chatted, chatting, chatter • Plan: planned, planning, planner • Sad: sadder, saddest • Slim: slimmer, slimmest
However, the general rule does NOT apply when the word is a digraph (that is, the vowel comprises two letters): • Float: floated, floating • Sweet: sweeter, sweetest • Repeat: repeated, repeating
Words with a single vowel in the last syllable are treated differently. In these cases, it depends on where the stress lies on the vowel sounds. For example, regret has a stronger stress on the second syllable, so the general rule applies: • Regret: regretted, regretting
When the stress is on the first syllable, the general rule does not apply: • Rocket: rocketing, rocketed
Other examples: • Admit: admitted
36 Effective Writing Doubling of Last the Letter
• Audit: auditing • Begin: beginning • Button: buttoning
Note: Words ending with -c, such as panic, take a -k (not another -c). Words ending with -x NEVER have the -x doubled.
Effective Writing 37 Rules of Grammar
38 Effective Writing CHAPTER 4 Getting Started
The key role of a technical communicator is to deliver technical and/or complex information to readers, listeners or viewers in a manner that is applicable to their needs, background and level of comprehension. The challenge is to bring enlighten- ment and understanding to non-technical audiences. However, for most people, this is easier said than done.
You may or may not have found yourself in a position where you have been given a writing task. Most of you have produced documents of one kind or another, but how effective was your writing? Did your readers understand it, absorb it and make use of it? Did you plan your writing task? Was there a review process? Which standards did you adhere to? Did you produce a paper document or was it meant for electronic delivery?
Getting started on your document task may not be as straight forward as you first thought. However, regardless of the complexity of your task, the following are essential components that must be established before you undertake any document project: • Start at the Beginning. • Evaluate the Aim of your Document (page 40). • Determine the Document Type. See “Document Type” on page 41. • Plan your document. See “Document Planning” on page 43. • Analyse Your Audience. See “Your Audience” on page 51.
Start at the Beginning
All documentation tasks have the same life-cycle, starting at the beginning. Before the first line of text gets written, the following tasks need to be undertaken: • Gather information. You start by researching and planning the project you are going to write about. You need to gather information from people, so you need to have good interpersonal skills. • Form your team. These are your Subject Matter Experts (SME), who shall col- laborate with you to write the documentation. There is also a key person who
Effective Writing 39 Getting Started
will “own” the project - the Project Manager or Project Owner, depending on the project. • Plan your reviews. Find out when the deadline for production is required and work from there to decide on a review process. Decide who shall conduct the reviews and when. You need to describe the project to other people, too, and many of these people will be required to check your work.
Evaluate the Aim of your Document
Ask yourself ‘why am I writing this’ and ‘what am I trying to achieve?’ If you don’t know, the chances of writing good specifications, reports, instructions or help are remote. The following table is an example of defining the aim of a document:
TABLE 6. Document Aim
The Situation Your Documentation Task Your Aim Your readers are Police You write a User Guide to The Police Officers feel Officers who will be using a show how easy it is to use relaxed and at ease with new Case Management Sys- the new system and how it the new software pack- tem to manage cases, store saves time entering data age, confident that they information about the cases when compared to the old are doing their job more and store associated data to system. effectively. share with other Police Officers
If you define your aim, you can then evaluate all information, arguments and rec- ommendations against that aim. For example, you might be writing a report on Firewall Software, but your aim is different if you need to write a one-page sum- mary or a 100-page technical specification.
Let’s define your aim as:
Aim: Explaining how firewall software protects the company’s data.
With this aim in mind, you can decide on the most relevant information. You might decide to: • Exclude alternatives to firewall software. • Exclude a review of different firewall software packages. • Stress the specific company information most at risk. • Look at the cost of introducing the software compared to the cost of losing data. • Describe the worst-case outcome. • Examine the technical issues to overcome in using firewall software.
Setting down your aim must be the first step in any piece of writing. By focusing your thoughts, you have started to think clearly about what your readers need to know.
When working out your aim, you may need to clarify the task by asking your supervisor or colleagues questions about the task. Keep asking questions until you have a clear idea of why you are writing and what you want to achieve as it will help collect the right information and decide how to present it to your readers.
If you have more than one aim, sort them into priority order.
40 Effective Writing Document Type
Document Type
Understand the type of document you are writing.
Technical documents come in all shapes and sizes, but they all share the same goal of communicating information clearly. Deciding what type of document you need to write is an important first step as it influences your approach.
The following document types are typically the kinds of documents that are gener- ated in the workplace: • Specifications • Reports • Help Documentation • Technical Manuals • Official and Accountable Documents
Specifications
There are two types of Specification Documents that are most likely to be produced in the AFP. Their purpose is to present a requirement in a clear, accurate and fully descriptive manner. This is the Requirements Specification.
The Requirements Specification should enable the reader(s) to propose a solution to meet those needs. This is the Technical or Design Specification, which subse- quently becomes the contract between the originator and the recipient.
Requirements Specification. These documents describe the work that needs to be done from information gathered in the analysis and/or the field. They can be as simple as the recording of data or more thorough works that include: • the problem or issue examined • the method or equipment used • the data collected • the implications
Technical or Design Specifications. Technical or Design Specifications typically consist of descriptions of the features, materials, uses and workings of a new prod- uct. Good specifications concentrate on graphics, data and illustrations rather than written descriptions. Think of a patent application as a good example.
Reports
Reports cover a wide range of topics. Many reports are generated electronically from data stored in databases, but these are not the types of reports that require writers to gather data, analyse data, format the document and publish the report. Business reports convey information to assist in decision-making. The report is the means to present this information.
Technical Evaluation Reports. Think of Evaluation reports as feasibility studies. They describe technical information in a practical and logical way to determine whether something is possible. For example, a technical evaluation report into set- ting up an on-line Leave Request form for a corporation. It would first of all deter- mine whether this was possible, then it would describe the process of development, pointing out problems along the way. It is NOT a recommendation for the corpora- tion to set up its Electronic Leave Request form.
Effective Writing 41 Getting Started
Technical Recommendation Reports. These reports describe recommendations derived from the evaluation report. They advise decision-makers to adopt the best solution. You can combine evaluation and recommendation reports.
Help Documentation
Procedures, set-to-work instructions, shut down instructions, how-to-do-it docu- ments with a user focus style of writing are written in a format called Help. Help documentation usually includes Frequently Asked Questions, text search, index and/or glossary. Help documents are Technical Manuals for a User type audience. Help is mostly authored for on line users, and the interface standard is maintained by companies such as Microsoft, Sun, Oracle etc.
Technical Manuals
Technical Manuals focus on the general description, detailed description, operation and use of appliances, equipment or software. Technical writers use technical man- uals to describe step-by-step procedures and technical detail that anyone can under- stand and follow.
Official and Accountable Documents
Accountable Documents are Commonwealth Records for the purposes of the Archives Act 1983 and are therefore required to be managed in accordance with that Act. Examples of Offical and Accountable documents are as follows: • Memos and Minutes • Witness Statements, Police Statements • Subpoenas and affidavits • Notebooks, diaries and fieldbooks • Briefs • Mention Brief (the initial brief) • Hearing Brief (upon a not guilty plea)
Documents such as these do not fit into a specific category, nevertheless, they are subject to the same principles of Effective Writing as described for for all docu- ment types.
42 Effective Writing Document Planning
Document Planning
Well-written documentation should be easy to: • Read • Understand • Access
To do this, when you are writing you need to know: • Who is the target audience? • What is their level of proficiency? • What special requirements are needed? • Where will the product be used?
Define each of these during the planning process. Remember to plan and not write ‘on the fly’ to meet deadlines.
Planning Technique
To achieve this goal, outline your requirements first. If you have been involved in the project from the start, you should have an understanding of the system, applica- tion or topic. If not, now is the time to consult your subject matter experts, read the specifications, and research the system/application until you have a sufficient working knowledge to continue.
The sooner the writer is involved, the easier it is to plan and write the required documentation.
The following technique is a good way to get started. • Think about the topic • Read the specifications, talk to subject matter experts • Write down every main key word you can think of
Think about the topic: what is its PURPOSE, what is the REASON FOR ITS CRE- ATION and what is the document’s OBJECTIVE? Let your mind wander freely about the subject, referring back to it as your day progresses.
Effective Writing 43 Once you have organised your thoughts, COLLECT, CREATE and ASSEMBLE the information in the form of keywords and key phrases. Write them all down.
For Example:
TABLE 7. Document Planning Techniques
Subject Possible topics The sun its temperature its composition its unusual phenomenon its relative size Ultrasound in medicine its physical properties equipment used medical uses advantages
Outline
Divide your keywords into groups of similar elements. Now organise your key- word groups in priority order of importance. Try to assemble your keywords according to what is most effective for the reader. Some methods that work include: • Simple to complex • Least important to most important (or the other way around) • Least controversial to most controversial • Most convincing to least convincing (or the other way around) • Most interesting to least interesting
Add or delete words as you progress. Your list should gradually evolve into a series of headings and sub-headings.
Plan the Sections
Plan the sections and sub-sections that you need. Write your document so that read- ers: • extract the main points without necessarily reading the whole document. If you don’t organise your document well, readers may miss important information. It is up to you to present your information in a readable and well-organised way. • easily find the information that interests them. You should write informative summaries, clear instructions and a logical arrangement to let your readers pick and choose the parts they want to read. • quickly absorb the crucial information they need to know. As readers will not read from the opening page to the last page, good organization here is essential. This is just as true of a manual where readers need to find out how to fix a prob- lem or a report where the reader wants to find the reason for a technical deci- sion.
For example, think of a good Internet page. Isn’t it easy to navigate and get the information you want quickly? So it’s a good idea to write down the sections and subsections you need to plan your document.
44 Effective Writing Document Planning
Use Strong Headings
Write your headings using strong verbs and specific nouns. When you have your sections and subsections (Volume/Chapter/Section), your Headings and sub-Head- ings, give them strong, active verbs and specific nouns. This is important because: • Use of a strong verb transforms the look and feel of the document. • Strong verbs and nouns invite a more direct and interesting style and help keep you organised and focused on the topic. • Headings break down information into shorter, easier-to-handle containers to keep you close to your original aim and your readers’ needs.
TABLE 8. Use Strong Headings
Weak Heading Strong Heading Searching for Cases in Case Management Case Management Search Gaining Access to the Cases Security and Access How to Cross Reference to another Case Add Cross Reference Choosing the Just-in-Time Principle Proposed Method Logging Entities and Actions Related to a Case Log Case Sorting – Alphabetical Order or Case Sorting Order? Filtering – What do you want to see? Filtering
Titles, Headings and Displayed Lists allow readers to: • See the main points • Sort major and minor categories • Scan documents effectively • Group tasks and long lists (see examples in book)
They help readers process the information faster if they are distinct and consistent.
Title Case
Capitalise the first letter of every work in a title except: • prepositions under four letters like “of,” “for,” and “in” • conjunctions under four letters like “and” • articles “the,” “a,” “an” when they appear within the title.
Dump Non-essential Information
Subject headings and subheadings reveal the structure of your document. They help the reader navigate through your information. With this in mind, look at your list again: • Once you have written down your sections, subsections and headings, review them. • Drop those that are not essential. • Work out the best order to let readers pick out the information they need.
Effective Writing 45 Use Distinct Headings
Titles and Headings should announce the MAIN IDEA or MAIN BENEFIT. Set headings off with bold text, larger font, spacing, shading.
Titles, Headings and Displayed Lists allow readers to: • See the main points • Sort major and minor categories • Scan documents effectively
They help readers process the information faster if they are distinct and consistent. Example: Documentation Tools
Technical Writers use the following tools, services and systems to develop a variety of document types: • Editing Software • Version Control and Delivery • Document Servers
Editing Software RoboHelp Office. Create on Line Help for company applications (for example, Time Recording, Leave Request software, ProjMan project management application).
MS Word. Used in collaboration with external authors to produce a vari- ety of documents.
FrameMaker. Technical Manual software used to produce complex paper based and electronic documents that are rich in content, format and design.
Version Control and Delivery
RoboSource. Source/Version control for RoboHelp documents. The Source Control database resides on the production document server and provides a safe, secure repository for all On Line Help projects.
Quadralay ePublish Pro. Used to publish electronic versions of docu- ments developed using MS Word and/or FrameMaker
Use Headings to Group Lists
Use titles and headings to group tasks and long lists.
46 Effective Writing Document Planning
Bad Example – this list is not grouped as well as it could be: List of Tools
MS Build. MS Build is the new build tool hiding behind Visual Studio 2005. It offers very similar functionality to Nant (see below).
Power Shell. Windows Power Shell is the new Command Shell from Microsoft. Sure it looks like a rip off of Bash, Korn etc, and it even implements aliasing to act like them. The big difference however is that it is built entirely on top of the DotNet framework, and all items are DotNet objects.
Team Systems. Team systems is a collection of tools from microsoft including Visual Studio Team Suite/Developer/Tester, Team Foundation Server and several other microsoft technologies.
Visual Studio 2008. Visual Studio 2008 is the latest development tool from Microsoft. It allows targeted framework development of the 2.0, 3.0 and 3.5 frameworks (all are based on the 2.0 framework).
NotePad2. Free C# Notepad application that replaces the dull windows notepad.
Edit Plus 2. A replacement for Notepad offering many powerful features such as syntax hi-lighting, web browser, spell checker and reg ex's.
TestDriven.NET. TestDriven.NET is a Visual Studio add-in that allows you to run the unit tests at the solution, project, class or method level without leaving Visual Studio. Highly recommended.
TestRunner. TestRunner is a Visual Studio add-in that does the same things as TestDriven.NET and much more like coverage and profiling; bit slower though. Currently unlicensed - you can only run it as an evalua- tion.
Holocentric. A modelling tool that is currently being trialled by AFP. The tool is currently being used by the Architecture Team as a repository.
XML Spy. The premier XML/XSL editor. Helpful for testing and trans- forming your xml prior to adding it to your code base.
XMetaL. XML authoring tool. Good for giving to clients that have no idea about XML. Will force users to conform to a schema.
GraphML Tools. A list of GraphML compliant tools to provide visuali- zations on XML.
Resharper. Productivity tool that every developer must have for VS2005
Effective Writing 47 : Good Example – grouped lists enable the reader to quickly scan the information they need: List of Tools
The Application Development team comprises software developers, software testers, business analysts, technical writers, Data Base Ana- lysts and others. A range of tools are available to help you do your job.
Microsoft
MS Build. MS Build is the new build tool hiding behind Visual Studio 2005. It offers very similar functionality to Nant (see below).
Power Shell. Windows Power Shell is the new Command Shell from Microsoft. Sure it looks like a rip off of Bash, Korn etc, and it even implements aliasing to act like them. The big difference however is that it is built entirely on top of the DotNet framework, and all items are DotNet objects.
Team Systems. Team systems is a collection of tools from microsoft including Visual Studio Team Suite/Developer/Tester, Team Founda- tion Server and several other microsoft technologies.
Visual Studio 2008. Visual Studio 2008 is the latest development tool from Microsoft. It allows targeted framework development of the 2.0, 3.0 and 3.5 frameworks (all are based on the 2.0 framework).
Code Editors
NotePad2. Free C# Notepad application that replaces the dull windows notepad.
Edit Plus 2. A replacement for Notepad offering many powerful fea- tures such as syntax hi-lighting, web browser, spell checker and reg ex's.
Test Tools
TestDriven.NET. TestDriven.NET is a Visual Studio add-in that allows you to run the unit tests at the solution, project, class or method level without leaving Visual Studio. Highly recommended.
TestRunner. TestRunner is a Visual Studio add-in that does the same things as TestDriven.NET and much more like coverage and profiling; bit slower though. Currently unlicensed - you can only run it as an eval- uation.
Holocentric. A modelling tool that is currently being trialled by AFP. The tool
Avoid Heading and Paragraph Numbering
When typewriters were used to create documents, authors often used heading num- bering to reinforce the hierarchy; each heading in the manual had a number beside
48 Effective Writing Document Planning
it. This was necessary because authors couldn’t use other typefaces or type sizes to show each heading’s place in the document structure. Now that other typefaces and type sizes are readily available, it’s no longer necessary to use heading numbering in either print or online manuals.
Some types of documents use a numbering system to number every paragraph and list item. This is common in legal acts and regulations, as well as in large, complex technical specifications.
Numbering headings and paragraphs was also once used for cross-referencing in typeset documents and carried over into electronic documents. In some cases it is still in general use, for example, in a manual of electrical standards for buildings, you can cite the standard for breaker switches by referring to the heading or para- graph number. Word processors have made heading and paragraph numbering unnecessary in most documents.
If you must use heading numbering, be very careful to establish the numbering style and the structure in a Style Sheet. Even then, you should never assume that the numbering is consistent.
Effective Writing 49 50 Effective Writing Your Audience
Your Audience
Your audience is the intended or potential reader or readers of your technical docu- ments. This is the most important consideration in planning, writing, and reviewing a document. You adapt your writing to meet the needs, interests, and background of the readers who will be reading your writing. It’s a simple principle; talk so the person in front of you can understand what you're saying.
It's like saying, “Don't talk rocket science to a brickie.”
Poor audience analysis and adaptation is one of the root causes of most of the prob- lems you find in professional, technical documents, particularly instructions/proce- dure manuals.
Audience Type
Classifying an audience is not the intention of this section, as the audience for every document will change for a number of reasons. However, it is possible to describe audiences as those that fit into one of the following broad categories: • Experts: This type of audience is made up of people who probably designed, and tested the product/system you are writing about. Readers who are not in this category will find it hard to understand documents written for experts. For- tunately, they don’t WANT to read them, either! Experts have trouble commu- nicating their ideas and knowledge to the technicians and management, but employing good Technical Writing skills will overcome this gap. When writing to Experts, there is no requirement for writing extensive back- ground information. Technical terms or acronyms need not be defined except where your analysis reveals any unfamiliar technical terms.
Do not just present a concept to an expert. Explain its parts and processes in detail.
• Technicians: These people are your primary Technical Manual audience. They build, operate, maintain, and repair the products/systems that the experts design. Technical knowledge is high, but you must come across to them with a hands-on, practical approach or you will lose them. • Managers: They make all the business decisions, administer economic control, and hold legal precedence over the products/systems that you are writing about for the experts and technicians to work with. This type of audience usually have only a little technical knowledge about the product/systems, and prefer to read about them in a non-technical, “black box” manner. When writing for managers, apply the following strategies: • Distil key information into an executive summary. • Present information in order of importance. • Emphasize information that will aid in making decisions. • Present sufficient background information in your introduction. • Put long, technical explanations into appendixes. • Use graphs and illustrations. • Explain technical terms in plain English. • Users: These are your primary Help manual audience. These readers have little or no technical knowledge. The documents they read are those that will show them how the product/system will accomplish their tasks.
Effective Writing 51 You will usually have more than one audience. For example, your Technical Man- ual may be read by Experts and Technicians, but Managers need the information, too. Rather than writing two manuals, include sections/chapters for your primary audience (usually Technicians), then make use of headings and introductions to alert your audiences about where to go and what to read.
Alternatively, put the supplemental information in appendixes or make use of cross-references to more appropriate volumes/chapters.
Match Content to Your Audience
Match your content to your readers’ knowledge. As always, your readers are all- important. Writing for the public or writing for specialists will alter how much technical information you can include.
If you are in doubt, aim for the simpler approach. It’s much better to take a little longer to explain something so everyone can understand it than to use jargon that’s a short-cut which alienates or confuses some of your readers.
However, you still have to draw a line somewhere. For example, you may have to write for both technical and non-technical readers. Suppose you have to describe how fuel injection works to a bus company maintenance workshop. You may have to assume the expert and the non-expert audiences both understand common terms such as injector pulse, throttle stop screw and thermostat. But you may need to explain more complex terms, such as base pulse constant and Volumetric Effi- ciency Table even if expert readers know the terms. The following example illus- trates two approaches to a technical description:
Poor Technical Writing: If the TPS closed throttle threshold exceeds 0.5v, a transitional surge occurs when switching VE maps between the closed throttle VE table and the closed loop VE table. At engine speeds above 1500 rpm, this is not a problem, but idle and low speed cruising are affected because the IAC has stepped open to 100%. Without any air bleed past the IAC stepper motor, a lean condition can exist causing hunting and, in extreme cases, stalling. To create slower transient steps and provide a greater range of steps for the IAC motor, a slight adjustment to the throttle body blades may be all that is required to drop the TPS threshold to a satisfactory level.
Concise and Easy to Read: If idle speed is too high or if low speed surging occurs, adjust the throttle stop screw until the Throttle Position Sensor voltage is less than 0.5v.
Readers can usually handle a few specialist words or terms if the writing style is concise and easy to read. To make this job easier, employ writing techniques that make it easy for your audience to understand your message. For example: • Use examples, analogies and case studies that fit the audience. • Describe HOW first - leave the What and Why for the end. • Start each section with an overview of the essential information (see The First Page on page 59). Easy Reading also means starting every chapter and section with a brief overview of the essential information, and ending it with a sum- mary. • Make headings and sub-headings stand out. On each page, there should be at least one heading, with sub-headings clearly and concisely formatted to stand out.
52 Effective Writing Your Audience
Use You and We
Use “you” in Help text to add familiarity. It's easy to read when the text is in a con- versational style. The pronoun “you” includes “a person”, or “people”, which is recommended when writing on-line Help text for computer applications. For exam- ple: You can add a log entry to the case using he right mouse click options. You can resize the screen by dragging the lower right corner with the mouse cursor.
Using “you” involves your readers and makes the message relevant to them. When you use “you” to address readers, they are more likely to understand what their responsibility is. For example: Copies of leave forms must be provided. You must provide copies of your leave forms.
Use “we” to refer to your team, group or agency for the same reasons. By using “we”, you state clearly what your group or team requires and what your group’s responsibilities are. It also keeps your sentences shorter and makes your document easier to read. For example: Leave applications will be reviewed to ensure that rosters are not dis- rupted. We review your leave applications to ensure that rosters are not disrupted. The Office of Consumer Affairs will process your application within 30 days after receipt. We’ll process your application within 30 days of receiving it.
Effective Writing 53 54 Effective Writing CHAPTER 5 Document Structure
A document's structure reflects its logical organisation of ideas, and a document's formatting visually expresses this structure. While focusing on a document's pur- pose, organise your information using logical principles such as grouping and sequence.
Documents that are well organised are easy to improve.
Structure and the Table of Contents
The Table of Contents is a summary of the chapters and headings, and is normally compiled when the document is complete. However, the TOC is also the one place in the document where overall structure can be examined, so why not get the struc- ture right at the start? Organise the initial level of detail to go down to three heading levels, or to the level which contains one key idea.
Principles to remember: • The opening words of a sentence should contain the major point or general idea of the sentence. • The opening sentence of each paragraph should contain the major point or idea of the paragraph. • The opening paragraph of a section should state the major point or general idea of the section. • The opening section of a document should contain the major points or general ideas in the document.
Headings. In your technical documents, instructions and/or procedures, make good use of headings. Normally, you'd want headings for any background section you might have, the equipment and supplies section, a general heading for the actual instructions section, and subheadings for the individual tasks or phases within that section.
Lists. Make heavy use of lists, particularly numbered vertical lists for the actual step-by-step explanations. Simple vertical lists or two-column lists are usually good for the equipment and supplies section. In-sentence lists are good whenever you give an overview of things to come.
Effective Writing 55 Document Structure
Warnings, Cautions, Notes. Alert readers to the possibilities of damage to equip- ment or themselves and others. Make a Note that stands out in instances where waste can occur or cause the entire procedure to fail. Companies have been sued for lack of these special notes, or for poorly written warnings.
In Help documents, the use of a Tips paragraph can be the answer to highlighting short-cut, an easy way to do something, a “hey, look at me” feature, which you can use to break up a long list of steps or make an otherwise boring section a worth while read.
Number, abbreviations, and symbols. Instructions also use plenty of numbers, abbreviations, and symbols. Use them in accordance with the appropriate stand- ards.
Paragraph Structure
Paragraphs are blocks of text that support a main point, and all sentences in the par- agraph should clearly relate to that point in some way. The paragraph's focus is the specific information that discusses the main idea in greater detail and has a begin- ning, a middle, and an end.
After you write your paragraph, examine the details or examples in the sentences that you wrote. Was there anything there that has unified the sentences? What do your sentences have in common? Now add an opening sentence to your paragraph using this information.
If you know what the main point of the paragraph is, write that first as clearly as you can. This is the Topic Sentence.
Expand on the key words in this opening sentence to write the rest of the para- graph. The sentences should explain “How?” or “Why?” or “What examples can I provide to convince a reader?” After you have added your supporting information, review the topic sentence and make sure you have been consistent.
Weak Paragraph: Limited investment in the housing sector makes it practically impossible to allocate sufficient resources for urban dwellers' housing needs. A high rate of urban population growth has increased the country's needs for housing. A small group of city officials has laid out a new plan to combat the crisis. A solution to the housing-shortage problem is a vital policy issue here. The housing problem has grown in the last twenty years.
Although the sentences are related by the topic (housing shortage), each sentence makes its own separate point. There are no links to the sentences before or after. The result is a group of related yet separate ideas instead of one coherent para- graph.
Improved Limited investment in the housing sector makes it practically impossible to allocate sufficient resources for urban dwellers' housing needs. In fact, the problem has grown in the last twenty years. Because a high rate of urban population growth has increased the country's needs for housing, a solu- tion to the housing-shortage problem is a vital policy issue here. A small group of city officials has laid out a new plan to combat the crisis.
Each separate fact now flows into the next, creating a coherent whole.
56 Effective Writing Use Examples, Tables and Illustrations
The Topic Sentence
The topic sentence describes the main point in a paragraph. It gives the reader a sense of direction, indicating what information will follow.
Placement of the Topic Sentence
Make your topic sentence the first or second sentence of a paragraph. It can be placed near the end of the paragraph, but it is rare that it works in this position.
Supporting a Topic Sentence with Details
To support a topic sentence, consider the details provided in the paragraph’s sen- tences, which can contain some or all of the following information: • examples • a story that illustrates the point you're making • a process • comparisons and contrasts • analogies (for example, “X is similar to Y because... “) • cause and effect • term definitions
New Paragraph
A new paragraph means we are switching to a new idea, changing time or place or breaking up a complex topic
Reasons for beginning a new paragraph • a new idea or concept • highlighting an important point • a change in time or place • emphasising a contrast • a change in speakers in a dialogue • lengthy descriptions or procedures require some breaks
Use Examples, Tables and Illustrations
When you write up your technical information, remember to use examples, tables, illustrations and analogies to explain difficult information or new ideas. A simple example or illustration can go a long way to making technical writing understanda- ble, or use simple analogies: “The computer hard disk is like a filing cabinet. It is divided up into fold- ers and documents”.
Illustrations can provide your reader with a large amount of information about an object or topic in a very small space. An illustration can accurately depict the form of an object, help the reader to visualize how the object functions, or show the rela- tionship of one object to another. It allows you to focus your audience's attention precisely on the details that you are describing.
Effective Writing 57 Document Structure
People think much faster than they read. Show a relevant illustration, and eyes will instantly absorb the whole image in preference to reading and understanding text. The more effective the illustration, the more lasting the image. To use illustrations effectively, follow these guidelines: • Choose appropriate objects to illustrate (for example, bar graphs, pie graphs, diagrams, photographs, exploded views, schematic diagrams). • Make your illustrations clear and easy to understand. Incorporate only those details that will be relevant. • Label the elements of your illustration clearly. • Identify each illustration with a figure number and a caption. • However you use illustrations, be they diagrams, photos, maps or whatever, they must be good quality and professional. • Use illustrations to communicate, not to decorate. • Choose the appropriate type of graphic for the meaning you want to convey. Photographs often provide too much information. • Put illustrations where they are relevant. Put them where they convey your message. • Always give an illustration a caption to guide the reader to the point of its inclu- sion. Without a caption you risk giving the wrong message.
See An Exercise in Illustrations on page 80
Tables
Use tables to present data lists and comparisons, or graphs where the data is com- plex.
Number your tables and illustrations consecutively and place a List of Tables and a List of Illustrations after your Table of Contents.
Use tables to present information efficiently and eliminate clutter. before To make a copyright symbol, hold down the Alt key on the numeric keypad and press 0169. To make a trademark symbol, hold down the Alt key on the numeric keypad and press 0153. To make a registered symbol, hold down the Alt key on the numeric keypad and press 0174. after
To insert a symbol, hold down the Alt key and type its ASCII number on the numerical keypad.
Symbol Name ASCII Number © Copyright 0169 ™ Trademark 0153 ® Registered 0174
58 Effective Writing The First Page
before
after
The First Page
Avoid starting with Background, Introduction or Overview. Instead, use the open- ing page to present the essential information, for example:
Effective Writing 59 Document Structure
Conventional Opening. This is the conventional method of opening a document titled “Report into Firewall Software”: Report into Firewall Software Background The IT Assessment Group has drawn this report together to examine the alternative ways of protecting the company's data. In particular, the con- cept of firewall software, defined as software that can be used to protect an organization from viruses and unauthorised entry into databases and its use within the organization is assessed. In order to assess the alterna- tives available, six independent technical evaluators were briefed on the company's databases, existing procedures. This report draws on the con- clusions of the six evaluators.
Essential Information Opening. The same document, but using an opening that focuses on the essential information: Firewall Software - Protecting the Company's Data Firewall software is essential to protect the company's databases from viruses or unauthorised access. By investing $20,000 in the latest soft- ware, the company will safeguard its 30,000 customer records and accounts and protect itself against credit-card fraud — estimated to cost the industry $2.5 billion a year.
Essential Information
By starting your opening page with the essential information, you give your readers a reason to keep reading. It also helps if you provide them with the benefits of the essential information. For example:
Statement of topic only Statement of topic and benefit This manual concerns the Krypton Atomic This manual describes how to program Robot. the Krypton Atomic Robot to do the tasks you require. This report discusses laptop computers. Laptop computers can save money and improve productivity.
60 Effective Writing The First Page
The First Sentence
Make sure the first sentence following the heading is complete. It is poor English to use a pronoun in the first sentence that refers to the heading. For example:
Incomplete first sentence: Use of Fireworks
They can be very dangerous to use without adult supervi- sion, and can cause bodily harm.
Complete first sentence:
Use of Fireworks
Fireworks, when used without adult supervision, may cause bodily harm because children: • light them incorrectly • stand too close to them • point them in the wrong direction
Effective Writing 61 Document Structure
62 Effective Writing CHAPTER 6 Write in Plain English
A well written technical document presents relevant information in a clear style. Unfortunately, companies still fail to employ good practices (pick up just about any computer manual) because their writers fail to use a clear, Plain English style. For example:
Original You can move files from the original folder, where it was first placed, to another folder that may have been created after the file was saved to its original folder. Click on the file to be moved and, before releasing the mouse button, drag the file to its destination folder and release the mouse button. If you want to move several files using the same technique, hold down the Ctrl key and click on each file that you want to move. All the selected files will be highlighted, and, when you select the last file to be moved and drag it to the destination folder, all the files previously selected will follow when you release the mouse button in the destination folder. [122 words]
Redraft in Plain English You can move files between folders using the Drag and Drop method. Click the file using the mouse and drag the file to the required folder. To move multiple files, depress the Ctrl key and select all the files that are to be moved. Drag the last file selected to the appropriate folder and the rest will follow. [58 words]
The PLAIN English Standard
PLAIN stands for Plain Language Association InterNational. Among its members are many Australian Government departments, who have implemented PLAIN English standards for their documents. State Governments, too, are forcing PLAIN English standards to be applied before official documents can be acceptable. For example:
Before: I give my Agent the power to exercise or perform any act, power, duty, right, or obligation whatsoever that I have or may hereafter acquire, relat-
Effective Writing 63 Write in Plain English
ing to any person, matter, transaction, or property, real or personal, tangi- ble or intangible, now owned or hereafter acquired by me, including, without limitation, the following specifically enumerated powers. I grant to my Agent full power and authority to do everything necessary in exer- cising any of the powers herein granted as fully as I might or could do if personally present, with full power of substitution or revocation, hereby ratifying and confirming all that my Agent shall lawfully do or cause to be done by virtue of this Power of Attorney and the powers herein granted.
After: I give my agent the power to do anything that I have a right or duty to do, now or in the future.
Before: Due to the fact that the plaintiff-appellant had up to this point in time sup- plied an insufficient number of widgets, defendant-appealer specified that, in the event that an insufficient number was supplied in the future, the con- tract would be held to be terminated, and deemed to be null and void and of no further effect. (55 words)
After: Because Smith Co. had not supplied enough widgets, Jones Co. said that, if this happened again, Jones would terminate the contract. (21 words)
For centuries, the long winded, legal/scientific style of writing (as illustrated in the above Before examples) fought to maintain its place as PLAIN English took over. Advocates of this academic, flowery style say that plain-language is the equivalent of baby talk or a drab, simplified version of English. They claim that the need to express complex ideas precisely makes plain language impossible.
But what is the point of being precise but unclear?
A Plain English approach to writing is every bit as accurate and precise as tradi- tional legal writing. It is clearer, shorter and faster. Most importantly, it is preferred by readers. Legislative drafters argue that their only audience is the legislator who requests a law or the judge who may interpret it. What about those who have to read it because they are directly affected, such as administrators, professional groups and, most importantly, the citizens whose lives are directly affected by the legislation?
For many years, Governments around the world have been changing to Plain Eng- lish standards of writing. The following is from the Parliamentary Counsel of New South Wales: "The ordinary person of ordinary intelligence and education [should] have a reasonable expectation of understanding . . . legislation and of get- ting the answers to the questions he or she has. This is of critical impor- tance.”1
1. Dennis Murphy, Plain Language in a Legislative Drafting Office, Plain English and the Law, supra note 2, at 50, 51 (stating that the “law should be drafted in such a way as to be intelligible, above all, to those directly affected by it”; and that, while laws cannot always be made intelligible to the average citizen, “every effort [should] be made to make them intelligible to the widest possible audience”).
64 Effective Writing Plain English Writing Techniques
Authors of legal and legislative text are required to write in accordance with politi- cal and employment realities. Adopting a Plain English style has meant changing the attitudes of such drafters to be more open minded and informed.
Here are a few more examples of Government adopting Plain English standards: • The Law Reform Commission of Victoria redrafted Victoria's complex Takeo- vers Code (they cut it by almost half). • The Parliamentary Counsel of Queensland and of New South Wales have pub- licly endorsed a plain-language style of drafting.1
A Commonwealth Inquiry into Legislative Drafting released a report saying that “the Plain English style developed by the drafting agencies since the mid-1980s has made new Commonwealth legislation much easier to understand.”2
Recently, the organization that represents all Australian road authorities drafted a proposed new set of uniform national road laws. They are "written in plain English to make them easy to understand.” They have been approved by the Office of Legislative Drafting (the Commonwealth agency that writes regulations), which was involved in the drafting.
Plain English Writing Techniques
Plain English means writing in a simple style that anyone can understand. This is not the way we learn to write at school. The culture of academic writing and busi- ness and scientific writing is the dull, long-winded, passive style. To write in plain English, you should: • Avoid Avoid Excessive Detail and Avoid Word Padding. • Write in a Positive Manner • Use the Active Voice, compared to the Passive Voice. • Avoid Long Sentences. • Use Simple Words. “I never write metropolis for seven cents when I can get the same price for city. I never write policeman when I can get the same money for cop.” Mark Twain. • Use Analogies, Graphics and Tables • Use Pronouns Wisely
Avoid Excessive Detail
Have you seen readers going through documents, using a highlight pen to find the key words, facts and figures? They do not highlight phrases such as: As you will be aware, the purpose of this document is to... in the order of... Readers want to take specific information from technical documents.
1. Office of the Queensland Parliamentary Counsel, Annual Report 1992-1993; Parliamen- tary Counsel's Office & Centre for Plain Legal Language, A Discussion Paper: Review and Redesign of New South Wales Legislation 3, 9 (1994). 2. House of Representatives Standing Committee on Legal and Constitutional Affairs, Clearer Commonwealth Law at xxii (1993).
Effective Writing 65 Write in Plain English
As long as you guard against going into excessive detail, replacing general infor- mation with specific information will improve your technical documents. For example, if a manager wants to know why production stopped for an hour on the assembly line, the author has to decide just how specific to make the message.
TABLE 9. General vs Specific
General Specific heavy precipitation during the period Fifty cm of rain in 48 hours excessive heat 42 degrees Centigrade select the appropriate key Click Alt-B
Make your point clearly rather than use the following words: • several • numerous • extensive • excessively • insufficient • massive • enormous • big • tiny • undersized • minimal • a significant increase (except when used in a strict statistical sense • to a considerable extent
As long as you guard against going into excessive detail, replacing general infor- mation with specific information will improve your technical documents.
Too General Problems arose in a number of areas of the stock transportation device that required intervention by an appropriately qualified member of staff so remedial action could be taken.
Specific As the temperature rose to 120 degrees Fahrenheit, the coolant for the metal rollers overheated causing the conveyor belt to jam. To keep the belt working, a mechanical engineer had to reset the timer and rollers on the conveyor belt, replace the coolant and slow the belt by 25% to 200 feet an hour.
Excessive Detail Monitoring the temperature saw a rise from 80.5 degrees Fahrenheit to 124.5 degrees Fahrenheit causing problems in the coolant’s temperature. As the coolant’s optimum operating temperature is 80 degrees Fahrenheit, the result was an expansion of the coolant beyond its maximum operating temperature level of 105 degrees Fahrenheit. This in turn led to a failure of the conveyor belt that was rectified by the mechanical engineer assessing the exact cooling coefficients needed with a possible ambient temperature above the manufacturer’s recommended levels.
66 Effective Writing Plain English Writing Techniques
Three reduced settings were considered, namely reducing the belt speed by 10%, 20% and 25%. These would lead to a reduction in the in-line assem- bly velocity of 80 feet, 160 feet and 200 feet an hour respectively. The optimum setting was 25.32% of the previous 800 feet an hour rate. However, before this was set, the engineer had to replace the 3.5 gallons of coolant used and reset 42 of the 360 rollers on the belt.
Just how specific your writing should be depends on the reader and your reason for writing. If our example, if you were trying to identify the reason for the belt stop- ping for a technical manager who needs to act to stop the fault reoccurring, you would need to go into technical details of the specific failure. If you are writing for non-technical manager who wants to know why there’s a problem and how you fixed it, the specific information shown is enough.
Choosing how specific your information should be is a constant problem for the technical writer. Remember, you’re trying to pitch the information exactly for the needs of the reader. Aim to write and describe concrete information without stray- ing into irrelevant information.
Remember: • Replace General information with Specific information • Depth of technical detail depends on your audience • This is the hardest part of Technical Writing!
Fuzzy Meanings
Some words automatically generate an image that is inconsistent with other read- ers. The cause of this inconsistency is the use of general terms where a specific term should be. Try this exercise:
Have any number of people write down a number between 1 and 100 to best indi- cate the amount (percentage) of time that each of the following words conveys:
Time Percentage Time Percentage Often Always Sometimes Never Usually Most of the time Occasionally Seldom A lot Almost always Rarely Frequently Quite often
Compare the results with others. Although there may be some similarities, figures will vary widely across a given audience. This means that your message will be interpreted differently be almost everyone who reads your document.
Avoid Word Padding
“The best way to be boring is to leave nothing out” - Volt air e
Padding is the enemy of good writing. Unnecessary words and phrases clutter up sentences and obscure meaning. By comparison, economy of words is the mark of good writing. You have to learn to make every word count in technical documents.
Effective Writing 67 Write in Plain English
You must edit ruthlessly, cutting any word. Set yourself a target of cutting 10 to 20 percent of the words in your document.
Wordy To understand and interpret an applet, the browser must have a Java vir- tual machine at its disposal. This is the case, in particular with Netscape Navigator and Internet Explorer, as well as Sun's HotJava. However, we have already mentioned several times that many Web surfers are attached to older browsers with which they feel comfortable. This being the case, if you use Java you will limit the number of visitors who will be able to won- der at what your applets do. In addition, browsers have a configuration option which allows (for security reasons, for example) the Java virtual machine to be turned off. Cautious people make frequent use of this option.
(111 words)
Concise Browsers such as Netscape Navigator, Internet Explorer and Sun's Hot- Java can only use applets with Java virtual machines. If Web surfers use older browsers, which do not understand Java, or switch the Java option off for security reasons, you will have fewer visitors to your site. (46 words)
Omit unnecessary words
Many words and phrases fail to add anything to a sentence. Leave out words that you don’t use every day. “If you can't explain something simply, you don't understand it well.” ...... Albert Einstein
Watch out for: Quite, very, extremely, as it were, moreover, it can be seen that, it has been indi- cated that, basically, essentially, totally, completely, therefore, it should be remem- bered that, it should be noted that, thus, it is imperative that, at the present moment in time. Incorrect: I would like to assert that the author should be considered to be a buffoon. Correct: The author is a buffoon. Incorrect: It would be safe to say that Gregor Samsa is not the only char- acter in Franz Kafka's The Metamorphosis to undergo drastic changes. Correct: Gregor Samsa is not the only character in Franz Kafka's The Metamorphosis to undergo drastic change. Incorrect: Before going to the supermarket, we made a list of the groceries we needed in order to make the food that we intended to eat for dinner. Correct: Before going to the supermarket, we made a list of groceries that we needed to prepare dinner. Incorrect: Taking the time to utilise the Spelling Checker tool is a particu- larly useful action for operations where entering large amounts of text are the norm, for example, when generating an incident description. Correct: The spelling checker is useful when entering large amounts of text, such as an incident description.
68 Effective Writing Plain English Writing Techniques
TABLE 10. Wasted Words
Instead of…. Use…. He is a man who... He... Owing to the fact that... Since...... has been engaged in the study of...... has studied... It will be seen from a consideration of the data in Table 2 Table 2 shows... that... At an earlier date... Previously,... In the modern period of time,... Currently,... It is interesting to note that... OMIT Typical results are shown... OMIT It has long been known... OMIT (please see Figure One) (Figure 1)
Some words just add length: • Strike action Strike • Cutbacks Cuts • Track record Record • Wilderness area Either a wilderness or a wild area • Large-scale Big • Weather conditions Weather • This time around This time
People can meet rather than meet with; companies can be bought and sold rather than bought up and sold off; organisations should be headed by rather than headed up by, a chairman, just as markets should be freed, rather than freed up.
Write in a Positive Manner
Our daily lives are filled with enough frustration and general negativity; we don’t need a writer to bring us down with their negative writing! Negative writing includes all those “don’t do X” statements. We can easily turn negative writing into positive writing, a much better experience for both writer and reader.
Positive writing also helps readers remember what they should do. Positive lan- guage reinforces a reader’s memory because the “don’t” action is never introduced. It is easy to make our writing positive; simply swap the “don’t” action with the “do” action.
Note: Negative writing does come in handy when you are warning someone not to do something that can cause serious injury or death. For example, a warning on a toaster that reads “Do not immerse in water!” is much more effective than “Keep on dry land.”
Not, No, Nothing, Nowhere, Don’t, Won’t, Can’t, are negatives.
Yes, Do, Will, Shall, Can, are positives.
Negative: Don’t forget to shut off your computer. Positive: Shut off your computer
Effective Writing 69 Write in Plain English
Negative: Don’t expect a raise of greater than 10%. Positive: Expect a 10% raise
Negative: Don’t use a curling iron while sleeping. Positive: Use a curling iron only when awake.
Negative: Don’t take this medication on an empty stomach. Positive: Take this medication after meals.
Negative: Don’t let your grass reach a height of over 4 inches. Positive: Keep grass height under 4 inches.
Negative: Don’t eat rotten strawberries. Positive: Eat ripe strawberries.
Use positive terms wherever possible. Avoid crass and brusque speech.
Brusque: Employees must not leave dirty dishes in the sink. Disciplinary action will result in the failure of employees to clean up after themselves.
Positive: Employees must clean their own dishes to avoid disciplinary action.
Accentuate the positive
Research shows that it takes the mind longer to understand a negative statement than the same ideas stated positively.
For example: A reader can grasp: You can enter dates in DD/MM/YYYY format rather than: Do NOT use any other format except DD/MM/YYYY
Double Negatives
Double negatives are just plain wrong! It is grammatical suicide to use double neg- atives.
“I can’t get no satisfaction” is a double negative. So are the following examples: • I think the new financial initiative will not last barely a month. • The researcher decided not to run the test again because the results from previ- ous tests were hardly reliable. • Since his last speech gained little acceptance, the writer has not had no request to visit the forum again. • The explorers finally discovered that the place where they landed did not have none of the minerals they wanted. • The pilot could not find nowhere to land. • After being replaced, the pipes did not run no water as expected. • Arizona had scarcely no rain last summer.
70 Effective Writing Plain English Writing Techniques
• The storm rose so quickly that the road crews could not do nothing about clear- ing the highways. • There is hardly no worse challenge than the one concerning national defence.
Exceptions to the rule
The ban on using double negatives to convey emphasis does not apply when the second negative appears in a separate phrase or clause, as in I will not surrender, not today, not ever or He does not seek money, no more than he seeks fame. You must use commas to separate the negative phrases in these examples. Thus the sen- tence He does not seek money no more than he seeks fame is unacceptable, whereas the equivalent sentence with any is perfectly acceptable and requires no comma: He does not seek money any more than he seeks fame.
Famous double negatives: “a substance almost, but not quite, entirely unlike tea.” Douglas Adams, A Hitchhiker’s Guide to the Galaxy. “We ain’t got no badges. We don’t need no badges. I don’t have to show you any stinkin’ badges!” Alfonso Bedoya to Humphrey Bogart, Treasure of the Sierra Madre, 1948.
Use the Active Voice Overuse of the passive voice weakens your writing. Using the passive voice may lead to omissions in information, hide potential problems or leave readers unsure of the idea being conveyed by the author.
Passive and active sentences are structured as follows:
Active Voice: The subject of the sentence is the one doing the action: The researchers compared the behavior of two groups of children. The clerk was helping the customer. Students need good study skills to succeed in college. You should tell him.
Passive Voice: The subject of the sentence is now being acted upon. The actor moves to the end of the sentence with by or drops off altogether if it is unimportant or unknown. The verb must include a form of be, followed by a past participle (normally an -ed ending). The behavior of two groups of children was compared (by the researchers). The customer was being helped (by the clerk). Good study skills are needed to succeed in college. He should be told.
Using active verbs is the first rule of good writing. Passive verbs are long winded, ambiguous and dull. Active verbs make your writing simpler, less awkward, clearer and more precise.
Passive Verbs: The QMS Magicolor 2 Printer is equipped with two interfaces, one is known as the parallel interface, the other is known as the Ethernet inter- face. Whatever interface connection is needed, you will find that MS Win- dows 98 has already been preinstalled and your software applications are
Effective Writing 71 Write in Plain English
based on this platform. (50 words)
Active Verbs: The QMS Magicolor 2 Printer has Parallel and Ethernet interfaces. What- ever interface you need, you will find your software applications will work on the preinstalled MS Windows 98. (28 words)
Active Voice
Using active verbs and writing in an active style is known as using the Active Voice. Use the active voice unless you specifically need to use the passive voice.
Examples Passive: A refund was given to him by the hair regeneration company. Active: The hair regeneration company gave him a refund. Passive: A good score was achieved by the team. Active: The team achieved a good score. Passive: The correct response to the Save prompt depends on whether you want to save the data or Cancel the action. Active: At the Save prompt, Click Save. Passive: Attitudes were formed after the plaintiff’s testimony. Active: The plaintiff’s testimony influenced the jury’s attitude.
In scientific writing, passive voice is more readily accepted since using it allows you to write without using personal pronouns or names as the subjects of sentences.
For example: Experiments have been conducted on live monkeys.
Using the passive voice in this instance creates the appearance of an objective, fact- based discourse. You can write about research and conclusions without attributing them to particular people or organisations.
Use passive voice when the person or subject performing the action is obvious, unimportant, or unknown. If it is necessary to avoid mentioning a person directly, use the passive voice, because it highlights the action and what is acted upon rather than the person/organisation performing the action. The new highway will be completed sometime next month. (the focus is on the highway, not on the workers).
Going from Passive to Active
In switching your style from passive verbs to active verbs throughout your writing, you face several problems.
You need to be able to spot passive verbs. Often writers miss passive verbs or try to change verbs that are already active.
You can locate passive voice in your writing in much the same way a computer would. Look for a form of the verb “to be” (am, is, are, was, were, be, being, or been) followed by a past participle verb (a verb ending in ed, en, or t). Passive voice requires BOTH!
72 Effective Writing Plain English Writing Techniques
Your leave was approved (verb “to be”) by your supervisor.
A “to be” verb by itself is simply an inactive verb (shows no action). A verb ending in ed, en, or t by itself is a past tense verb and not passive voice.
Measure your use of passive verbs. One or two passive verbs per page will not ruin your style. Nine or ten will.
You need to know how to turn passive verbs to active verbs, for example:
Passive Verbs The experiment was conducted so that the relationship between the two theories could be examined. First, the cultures were prepared and then were examined under the microscope to see if any impurities could be found. Once the purity of the samples could be established, they were used in six independent tests. (51 words)
Active Verbs The experiment examined the relationship between the two theories. First, microscopic examination for impurities isolated pure examples used in six independent tests. (22 words)
Passive to Active: Who-Does-What
Write most of your sentences in the Who-Does-What order. This means starting the sentence with the main subject, followed by a strong active verb. For example:
Padded This idea is referred to by scientists as the Gridlock Theory.
(11 words)
The Who-Does-What order places scientists first, followed by the verb refer. This shortens the sentence to:
Concise (Who-Does-What) Scientists refer to this as Gridlock Theory.
(7 words)
The Who-Does-What order will cut out wasted words and encourage you to write your sentences with active verbs.
Padded Reloading new data is as simple as clicking the refresh icon to re-draw, or re-create, the window.
Concise Click the Refresh icon to re-draw the window and reload new data
Using this technique also makes it easier to write in the active voice:
Effective Writing 73 Write in Plain English
Passive Summary data of the selected record in the results list is displayed in the Quick View panel at the bottom of the screen.
Active The Quick View panel at the bottom of the screen displays summary data of the selected record.
When to use Passive Voice
The active voice makes sentences clear and direct, but there are occasions where an indirect expression is going to work better. Active: The dispatcher is notifying police that three prisoners have escaped. Passive: Police are being notified that three prisoners have escaped.
If the agent performing the action is obvious, unimportant, or unknown, use the passive voice. If you want to avoid mentioning the agent performing the action, the passive voice can be used. Active: Surgeons successfully performed a new experimental liver-trans- plant operation yesterday. Passive: A new experimental liver-transplant operation was performed successfully yesterday.
It is also effective where the highlight is the action and what is acted upon rather than the agent performing the action. Active: “Authorities make rules to be broken,” he said defiantly. Passive: “Rules are made to be broken,” he said defiantly.
In each of these examples, the passive voice makes sense because the agent is rela- tively unimportant compared to the action and what is acted upon.
Avoid Long Sentences
Long sentences make any document hard to read, so keep your average sentence between 8 to 15 words. You may go down as low as 6 or 7 words if you're writing instructions/procedures with many short, sharp sentences telling the user what to do. However, if you consistently get below 10 words, you're probably overdoing the technique of short sentences.
Long Sentence A highlight of the web site is the development of two types of electronic advisory systems - Expert and Technical where both of the systems inform the user about standards by either asking a series of questions which determine whether, how, and which specific parts of the standard apply to the user's activities, or addressing complex standards by placing in one location a large amount of information about the standard. (One Sentence - 70 words)
Shorter Sentences The web site offers both expert and technical advice sections. These explain standards by asking questions to find out if and how the standards
74 Effective Writing Plain English Writing Techniques
apply to the user. They also address complex standards by placing all the relevant information in one place. (Three sentences - 42 words)
Using a List to Shorten Sentences
Sometimes, it helps if you break long sentences into a list.
Long Sentence: A number of attachments are created for the CCR request, including the contact number entity for this CCR request, the CCR request document and all contact numbers associated with the upload. (One Sentence - 31 words)
Shorter Sentences: A number of attachments are created for the CCR request: • the contact number entity • the CCR request document • all contact numbers associated with the upload (4 sentences - 25 words)
Use Simple Words
Use simple words rather than complex ones. Many writers have difficulty keeping their message simple and clear. Instead of using everyday words they use complex or unfamiliar words. Simple, everyday words will help you get your message across. Too often technical writers use words such as additional, indicate, initiate and proliferate instead of the simpler extra, show, start and spread.
Take this example: This demonstrates an understanding of the history, diversity and common- ality of the peoples of the nation, the reality of human interdependence, the need for global cooperation, and a multicultural perspective.
A more readable style, would be: This shows we understand why history and common beliefs in each nation matters as across the world, people need to work together and respect their different cultural backgrounds.
Note: You needn't worry that abandoning many of these big words will impoverish the English language. Firstly, most of the big words in this section have little literary merit. Secondly, there are about 500,000 entries in The Oxford English Dictionary, and the non-use of 200 of them will hardly matter.
Complex Words As we noted in the preceding section, if you purchased additional printer options, such as a second printer tray, it is a requirement you verify its correct installation.
Effective Writing 75 Write in Plain English
Simple Words As we noted in the previous section, if you bought extra printer equipment, such as a second printer tray, you must check that you installed it cor- rectly.
76 Effective Writing Plain English Writing Techniques
TABLE 11. Changing Complex to Simple
Change Complex Words to Simple Change Complex Phrases to Simple Words Words
Change this…. …to this Change this… …to this articulate explain at your earliest con- soon venience culmination end be in a position to can endeavour try in accordance with as facilitate ease or help due to the fact that because indication sign in the amount of for reiterate repeat under the circum- therefore stances subsequent later in the event that if utilise use in reference to about Refudiate Reject or refuse in view of the fact because that
in order that so noted in our noted recorded pending receipt of awaiting at the present time now
Making difficult text simple
Before High-quality learning environments are a necessary precondition for facil- itation and enhancement of the ongoing learning process.
After Children need good schools if they are to learn properly. (Although the 'Before' paragraph does not mention it, the situation does involve schoolchildren.)
Before If there are any points on which you require explanation or further partic- ulars we shall be glad to furnish such additional details as may be required by telephone.
After If you have any questions, please ring.
Before Media Output Facility Error
After Paper tray empty
Before
Effective Writing 77 Write in Plain English
It is important that you shall read the notes, advice and information detailed opposite then complete the form overleaf (all sections) prior to its immediate return to the Council by way of the envelope provided.
After Please read the notes opposite before you fill in the form. Then send it back to us as soon as possible in the envelope provided.
Before Your enquiry about the use of the entrance area at the library for the pur- pose of displaying posters and leaflets about Welfare and Supplementary Benefit rights, gives rise to the question of the provenance and authorita- tiveness of the material to be displayed. Posters and leaflets issued by the Central Office of Information, the Department of Health and Social Secu- rity and other authoritative bodies are usually displayed in libraries, but items of a disputatious or polemic kind, whilst not necessarily excluded, are considered individually.
After Thank you for your letter asking permission to put up posters in the entrance area of the library. Before we can give you an answer we will need to see a copy of the posters to make sure they won't offend anyone.
[The following is written by Stephen Tyler, and appears in Writing Culture, edited (it says) by James Clifford and George E. Marcus (University of California Press, 1986). In his book “post-modern ethnography,” Professor Tyler writes: It thus relativizes discourse not just to form--that familiar perversion of the modernist; nor to authorial intention--that conceit of the romantics; nor to a foundational world beyond discourse--that desperate grasping for a sep- arate reality of the mystic and scientist alike; nor even to history and ide- ology--those refuges of the hermeneuticist; nor even less to language - that hypostasized abstraction of the linguist; nor, ultimately, even to discourse - that Nietzschean playground of world-lost signifiers of the structuralist and grammatologist, but to all or none of these, for it is anarchic, though not for the sake of anarchy but because it refuses to become a fetishized object among objects - to be dismantled, compared, classified, and neu- tered in that parody of scientific scrutiny known as criticism.
Use Analogies, Graphics and Tables
When you write up your technical information, remember to use analogies (includ- ing examples, comparisons and metaphors) tables and graphics to explain difficult information or new ideas.
Analogies, Examples, Comparisons
A simple analogy can go a long way to making technical descriptions understanda- ble: “The computer hard disk is like a filing cabinet. It is divided up into fold- ers and documents”. “Electricity is the flow of electrons along a conductor. Electron flow is similar to water flowing along a garden hose”.
78 Effective Writing Plain English Writing Techniques
“Pop-ups are like the tear-out cards in magazines, a form of promotion that, while intrusive, fits the medium”.
Brief definitions, while adequate, can be expanded with an example to ensure that readers understand an important idea. For example: Without an example: “Unhealthy lifestyles contribute to disease.” Using an Example: “Unhealthy lifestyles (for example, eating too much, lack of exercise and smoking) contribute to disease.”
Using comparisons can help clarify an explanation. Try comparing new terms or ideas with familiar, everyday objects: Without a comparison: “On the moon there is no atmosphere, no wind and no rain. Therefore a mark on the surface would remain.” With a comparison: “On the moon there is no atmosphere, no wind and no rain. Therefore a mark on the surface would remain through the ages; a footprint would last for millions of years.”
Graphics
There are many types of Graphics used to support text. Graphs, diagrams, photo- graphs, images, drawings, exploded views, schematic diagrams are all examples of Graphics in documents. For the purposes of simplicity, Graphics covers the follow- ing formats: • Illustrations. Including images, photographs, screen dumps, scanned images and other bit-mapped formats. Also includes Graphs, for example, bar graphs, line graphs and pie graphs. • Drawings. Line drawings, schematic diagrams, CAD drawings.
Graphics are crucial to instructions. When words cannot explain the step, graphics are often critical to the readers' ability to visualise what they are supposed to do.
Note: Every graphic must be referenced in the text.
Don’t add graphics to your document unless there is text that directs the reader to it. It is a general rule that each graphic should be labelled and numbered (in the form of a numbered caption) but if the text does not refer to it, then it doesn’t belong there.
The graphic must add value to the text. For example, the instruction: 6. Click OK to continue does not need a screen dump with an arrow pointing to the OK button with the cap- tion “Click to Continue”.
Graphics can provide your reader with a large amount of information about an object or topic in a very small space. An illustration can accurately depict the form of an object, help the reader to visualize how the object functions, or show the rela- tionship of one object to another. It allows you to focus your audience's attention precisely on the details that you are describing. For Example:
Effective Writing 79 Write in Plain English
Before This is a multipurpose passenger vehicle which will handle and manoeu- vre differently from an ordinary passenger car, in driving conditions which may occur on streets and highways and off road. As with other vehicles of this type, if you make sharp turns or abrupt manoeuvres, the vehicle may roll over or may go out of control and crash. You should read driving guidelines and instructions in the Owner's Manual, and WEAR YOUR SEAT BELTS AT ALL TIMES.
After
FIGURE 1. Example: Using Graphics
Illustrations. People think much faster than they read. Show a relevant illustration, and eyes will instantly absorb the whole image in preference to reading and under- standing text. The more effective the illustration, the more lasting the image. To use illustrations effectively, follow these guidelines: • Choose appropriate illustration (for example, bar graphs, pie graphs, diagrams, photographs, exploded views, schematic diagrams). • Make your graphics clear and easy to understand. Incorporate only those details that will be relevant. • Label the elements of your illustration clearly. • Identify each illustration with a figure number and a caption. • However you use illustrations, be they diagrams, photos, maps or whatever, they must be good quality and professional.
An Exercise in Illustrations
The exercise is to write a description of a bicycle for someone who has never seen, or heard of, a bicycle. Which do you think would work better?
Text Only Description: A bicycle is a self-propelled, two wheeled mode of transport. The operator of the bicycle sits on a seat mounted to the top of a frame that supports the two wheels, one in front of the operator and one behind. The front wheel controls direction. The operator uses a handlebar connected to the front wheel to steer the bicycle. The rear wheel propels the bicycle. It is con- nected to a pedal mechanism via a chain and sprocket. The operator exerts foot pressure on the pedal mechanism, which turns the chain and drives the rear wheel forward.
80 Effective Writing Plain English Writing Techniques
Illustration:
FIGURE 2. Bicycle
While the text description is concise and well written, it does not convey the cor- rect image in the mind of the person who has never seen a bicycle. The illustration, however, does this far more efficiently than the text. Ideally, the description would be accompanied by the illustration.
Tables
Use tables to present data lists and comparisons, or graphs where the data is com- plex.
Number your tables and illustrations consecutively and place a List of Tables and a List of Illustrations after your Table of Contents.
Use tables to present information efficiently and eliminate clutter. before To make a copyright symbol, hold down the Alt key on the numeric keypad and press 0169. To make a trademark symbol, hold down the Alt key on the numeric keypad and press 0153. To make a registered symbol, hold down the Alt key on the numeric keypad and press 0174. after
To insert a symbol, hold down the Alt key and type its ASCII number on the numerical keypad.
Symbol Name ASCII Number © Copyright 0169 ™ Trademark 0153 ® Registered 0174
Use Pronouns Wisely
The pronoun “you” also includes “a person”, “people”, which is recommended when writing on-line Help text for computer applications. It adds a dimension of familiarity. For example: You can add a log entry to the case using either the right mouse click options.
Effective Writing 81 Write in Plain English
You can resize the screen by dragging the lower right corner with the mouse cursor.
This may not be a good idea when writing Technical Manuals. Use a more active voice when the text is procedural or critical: Right mouse click on the link and choose Option 1. Resize the screen by dragging the lower right corner with the mouse cur- sor.
In informal English, the pronoun “you” can be used to imply a person that is not necessarily the reader. This can be mildly offensive, for example: The file is unrecoverable when you click the wrong button....
It is preferable to use third person: The file is unrecoverable when one clicks the wrong button... The file is unrecoverable when the user clicks the wrong button....
82 Effective Writing CHAPTER 7 Avoid Confusing or Ambiguous Text
The English language is fluid and ever-changing, but the way our diction, grammar and vocabulary changes should be imperceptible. The spelling of words has changed little over the last 300 years, but our pronunciation has, albeit in more sub- tle ways. As a result, speech patterns and dialects have crept in to our writing, mak- ing it ambiguous and confusing to some readers. Confusing and ambiguous text is often caused by using the following: • Abstract Words and Phrases • Redundancies • Jargon • Officious and Flowery Language (“Cop Speak”) • Acronyms and Abbreviations • Latin (and French) • Clichés • Repetition • Sexist Language • Misplaced Modifiers • Mixing American, Australian and British English • Archaic Words and Phrases
Abstract Words and Phrases
Abstract words are words and phrases that you can’t see or hear or feel or taste or smell. When you write, you want your readers to know exactly what you mean. Specific words convey a clearer message than abstract words which can creep into your writing without adding anything to the meaning. For example, what is a device, output or facility? Such words are so abstract they become meaningless to the reader. String them together, such as output device and you have instant jargon for the word printer. Add them to acronyms and you can produce CAS Facility which in turn means Civic Amenity Site Facility, which is jargon for the Council Recycling Site at Hume in the ACT.
Effective Writing 83 Avoid Confusing or Ambiguous Text
Table 12 on page 84 lists some abstract word examples.
TABLE 12. Abstract Word Examples • activities • structures • devices • amenity • inputs • facilities • sectors • outputs • amenities • systems • elements • aspects • operations • factors • variables • processes • concepts • resources • functions
Avoid confusion by being precise in your choice of words.
Tip: Use a thesaurus.
Choose words that: • specifically identify something or someone precisely to ensure there is no ambi- guity. • are familiar to most people or which relate to familiar things. • can be clearly understood by your audience.
For example:
Abstract Running our new facility will improve our system performance.
Specific Running database software will improve our system administration.
Abstract Running the latest database software will improve our payroll output oper- ations.
Specific Running the latest database software saves three hours printing the pay- roll report.
Vague phrases such as a number of, in due course, and at a later date also contrib- ute to abstract writing. Instead of this vagueness about time, be as specific as you can by giving a date, a specified time or at least use a single word such as soon or later.
84 Effective Writing Redundancies
Redundancies
Avoid unnecessary repetition of words or word meanings.
TABLE 13. Redundancies
Redundancies Corrected consensus of opinion consensus fewer in number fewer exact duplicate duplicate estimated at about estimated sum total sum whether or not whether in order to to elongated in shape elongated both of them both excised out excised at this time now
Take care to avoid these typical redundancies:
TABLE 14. More Redundancies (advance) planning (free) gift (armed) gunman at (12) noon (basic) fundamentals (close) proximity (end) result (frozen) ice join (together) (pair of) twins green (in colour) (poisonous) venom surrounded (on all sides) due to (the fact that) first (and foremost) (free) gift period (of time) refer (back) (actual) experience (advance) planning (advance) reservations (advance) warning all meet (together) autobiography (of my life) (awkward) predicament (baby) boy was born cease (and desist) cheap (price) cold (temperature) commute (back and forth) (difficult) dilemma each (and every) (empty) space filled (to capacity) (general) public (natural) instinct never (at any time) (null and) void (past) experience (poisonous) venom (pre-)recorded reason is (because) (regular) routine (small) speck (suddenly) exploded (unexpected) surprise
Things to think about....
Rice Paddy – Paddy comes from the Malay word for rice (padi), hence this is ety- mologically redundant, meaning rice rice.
Sahara Desert – Sahara Desert is apparently a repetition because Sahara may be derived from an Arabic word for sand or desert, which would mean Sahara Desert means desert desert.
Effective Writing 85 Avoid Confusing or Ambiguous Text
Avoid the Word ‘Please’
The word ‘please’ is an unnecessary word, especially when writing procedures (See “Procedure Writing” on page 167). When writing at work, an imperative call to action is all that is necessary, for example: Correct: Type in your password. Incorrect: Please type in your password.
Here are some more good reasons to avoid using the word ‘please’ when writing at work: • Using the word ‘please’ implies that there is an alternative. • Users of a system/application are confident that they are following the correct procedures because they are written as short, sharp commands. Using ‘please’ weakens that confidence. • It is a completely false assumption on the writer’s part that using ‘please’ makes your procedures ‘polite.’ Being ‘polite’ is about SPEAKING the words “please” and “thank you.” • The word please, in the context of a procedure, instruction, or error message, translates poorly in other languages.
Jargon
Do not use jargon in your writing. Jargon is the most common problem in technical documents. Technical Writers must always be on constant alert for jargon, acro- nyms, abbreviations and abstract words.
Jargon-ridden: To get the most screen real estate, max out the horizontal and vertical pixel options in 64 bit colour mode until the refresh rate goes troppo, then back off a bit.
Jargon-free: To fit more on your screen, use the highest screen resolution available in true colour mode before the screen starts to flicker.
Audience Jargon or Specialist Terms
More than any other writing problem, jargon depends on your audience. Write a manual for Visual Basic for existing users of the language and technical jargon is a second nature. The same technical jargon aimed at someone learning Visual Basic inhibits understanding. To those with no experience of Visual Basic the technical jargon is just “Greek to me”.
In the example, each of these professions needs these specialist terms. They specif- ically describe something, even if the word is not in the average person's vocabu- lary. Many of the words are in a good dictionary and all are in your spelling checker. So use such terms freely, offering explanations if you expect your readers to have problems understanding. For example, a doctor might explain the need for a tonsillectomy to a patient by saying, ‘You'll need to go into hospital for an over-
86 Effective Writing Jargon
night operation to remove your tonsils.’ But to use such an explanation in a report to his or her peers would be unnecessary.
TABLE 15. Specialist Terms
Profession Example Law affidavit, easement, surety Automotive spigot bush, EGR, ignition module Mathematics duodecimal, rhomboid, standard deviation Medicine angina, cerebral palsy, tonsillectomy Computers batch processing, JPEG, macros Coin Collecting Moose: High quality coin. Newp: New Purchase. Commem: Commemorative coin. Dog: Poorly preserved coin. Flip: Clear plastic coin holder. Hits: Nicks and marks on a coin. Moose: High quality coin. Forestry Biltmore stick: A tool calibrated to measure the diameter of a tree at breast height. Blaze: To mark a tree, usually by painting or cutting the bark. Buck: To cut trees into shorter lengths. Crook: Tree defect characterized by a sharp bend in the main stem. Frilling: The method of killing trees by inflicting a series of cuts around the bole and applying an herbicide to the wounds. Patch cut: A clearcut on a small area. Windthrow: A tree felled by wind. License Plate Col- nrp: Needs repaint lectors 3xh: Three extra holes Alligatoring: The deterioration of paint, resulting in a cracking of the surface. Booster: Un-official license plate. Dishpan: A plate with a deep, raised border. Jumpy: A plate where one or more of the numbers are misaligned. Waffle: A plate made from aluminium.
Email Jargon
E-mail has created some interesting jargon. For those of us who are novices to the meaning of this jargon, here is a list. • BTW - By The Way • FYI - For Your Information • IMHO - In My Humble/Honest Opinion • RTFM - Read The Manual (“Manual” here refers to any documentation) • LOL - [I] Laughed Out Loud [at what you wrote] • RSN - Real Soon Now • ROTFL - [I am] Rolling On The Floor Laughing [at what you wrote]
Effective Writing 87 Avoid Confusing or Ambiguous Text
• - grin • - hug
These are less common, but show up occasionally: • TTFN - Ta-Ta For Now • TIA - Thanks In Advance (also sometimes written advTHANKSance)
Email Jargon that is sometimes used in Help and Technical Docu- ments
The following email jargon should be avoided unless you are specifically writing about email usage. • spam - Unsolicited email sent to many people simultaneously, usually commer- cial, but occasionally political. • bounce - A message that was returned to the sender, either because the email address was incorrect or because there was a configuration problem on the receiver's end. Can also be a verb: “I tried sending email to my Aunt Mabel, but it bounced. I guess she doesn't work there any more.” • distribution list - A single email address that resends to many others, allowing a discussion to continue easily among a quasi-stable group of participants. Also called emailing lists or listservs (from LIST SERVers). • bot - A piece of software that acts on behalf of and in place of a remote human (from roBOT). • mailbot - A piece of software that automatically replies to email. • listbot - A piece of software that manages distribution lists. Also called a list- server or majordomo (after the name of a common list server). • post - Send to a distribution list or Usenet newsgroup, i.e. to a quasi-stable group of people. • flame - An electronic message that is particularly hostile. Can also be a verb: “Whooeee! I posted a rude cat joke to my company's cat-lovers mailing list, and wow, did I get flamed!” • lurk - To read messages anonymously (in either a mailing list or Usenet news- group) without posting. (Source: Guide to Effective Email by Kaitlin Duck Sherwood)
Don’t Overuse Technical Terms
Although a specialist technical vocabulary is necessary, don’t let this be an excuse to use the technical word unthinkingly. For example, in a desktop publishing man- ual you could use the terms folio, recto and verso. But why? The simpler page or page number (folio), right-hand page (recto) and left-hand page (verso) are eas- ier for the reader to follow.
Avoid Legal Jargon
There is no law that says you should litter your writing with whereas, hereby, here- inafter, said (and its blown-up cousins, aforesaid and aforementioned). This kind of antique jargon is a dying branch of legal vocabulary, and adds nothing to the mean- ing of your writing.
Instead of saying: I hereby declare....
88 Effective Writing Jargon
say: I declare.
Instead of saying: The aforesaid Arthur Jones.... say: Arthur Jones
The following table (Table 16, Legal Jargon Interpreter, on page 89) lists a few of the common words and phrases that should be avoided at all costs:
TABLE 16. Legal Jargon Interpreter He indicated... He said I have been employed by... I worked for I exited the patrol vehicle... I got out of the car I observed... I saw I ascertained the location of the residence... I found the house I proceeded to the vicinity of... I went to I approached the entrance... I went to the door The subject approached me... She came up to me I apprehended the perpetrator... I arrested the man I obtained an item that purported to be an envelope I got the envelope from her from the individual... I observed the subject fleeing on foot from the loca- I saw him running away tion... Declined to.... Would not
Altercation: It’s either a fight or an argument. Use altercation only if you can't find out and there is reason to believe "argument" or "argued" would be inaccurate.
Believe: “I believe the broken window, the ransacked house and the missing jew- elry is the result of a burglary.” You can think, can’t you?
Broke out: People “break out” of prison. A shooting “began” or a fire “started.”
Sparked. Fires are not “sparked by” anything. They are “started”.
Exit/exiting/exited: Leave, leaving, left, came out. “The car left the car park” is better than writing “The car exited the car park.”
Extract: This means removing broken head bolts from an engine or pulling a tooth. Use freed, removed or pulled from when writing about, for example, a person being “pulled from” a wrecked car.
Fled/fleeing the scene: Use fled or flee. For example: Bad: Witnesses saw the suspect fleeing the scene on a bicycle. Good: Witnesses saw the suspect flee on a bicycle. Bad: The prisoner fled on foot. Good: The prisoner ran away.
Effective Writing 89 Avoid Confusing or Ambiguous Text
Identities: Names.
The exception is when using the word name as a verb. Most suspects are already named by their parents. In such cases, use identify.
Informed: People usually tell people things. Sometimes they warn them. They never inform.
Locate: Find, as in Police are trying to find the suspect, rather than locate the sus- pect.
Person of interest: Resist the temptation to use this term. Instead of writing: Police say Smith is a person of interest.
Write: Police want to talk to Smith about xxx.
Stationed: Avoid writing reports using Stationed, for example: The Police were stationed at the market when the shooting started.
The term is redundant (not needed): The Police were at the market when the shooting began.
Suspect: Use only when appropriate. Someone who robs a bank is a robber until police identify the robber. Then they become a suspect.
Sustained: People don't sustain injuries. They suffer them.
Transported: Use took or taken. For example: Bad: She was transported to the hospital. Good: She was taken to the hospital.
Officious and Flowery Language (“Cop Speak”)
Avoid flowery and over-the-top language, even in official reports or legal papers. Plain English is much easier on the reader. It gives them less to read for the same amount of information and does not burden them with interpreting fancy terms for everyday things.
The following table lists nearly two hundred terms that often appear in official doc- uments. In most cases, using the alternative terms in the right-hand column will make your documents easier to read and understand.
TABLE 17. Cop Speak to Plain English Cop Speak Plain English a further meeting another meeting able to can above-mentioned mentioned above accordingly so / therefore additional more
90 Effective Writing Officious and Flowery Language (“Cop Speak”)
TABLE 17. Cop Speak to Plain English (Continued) additionally and adjacent to next to / near advice has been received that my officers have told me that advise you that / of let you know ... aforementioned mentioned before / mentioned above all things considered so / therefore alter / alteration change amongst among anticipate expect approximately roughly / about as a consequence of because of as noted previously as I have said (written) above as soon as practicable as soon as possible as you would be aware as you know ascertain find out / check assist / assistance help at an early opportunity soon at this point in time now / at present at your earliest convenience as soon as possible attached hereto attached please find be applicable applies be in accordance with accords with by virtue of under / because of commence start / begin commencement start / beginning completion end / finish comprise make up concerning about concur agree concurrence agreement consequent later consequently so / therefore considerable amount of a lot of / many / much contiguous to next to / near conversely but / on the other hand currently now / at present dated of dispatch send due to because of e.g. for example / for instance emanating from coming from embark on start endeavour try et al and others etc / et cetera and so on
Effective Writing 91 Avoid Confusing or Ambiguous Text
TABLE 17. Cop Speak to Plain English (Continued) experienced delays there were delays / had delays extremely very facilitate enable / make possible failed to did not falls within the responsibility of Bloggs Bloggs is responsible for familiarise you with make you familiar with for the duration of during for the purpose of to / for for your consideration for your decision / for your information forthwith immediately forward send further developments more developments / new developments a further meeting another meeting further to my letter concerning I am writing again about furthermore and / also hence so / therefore henceforth from now on hereby / herewith here / please find hereunder below however but I acknowledge receipt of thank you for I am advised that my department tells me that I am directed to advise you that the (minister) has asked me to tell you that I am grateful for thank you for I appreciate that I understand that / I know that I appreciate your thank you for your I can confirm that (Leave it out.) I consider that I think that / I believe that I refer to your letter dated thank you for your letter of I regret the delay / the delay is regretted I am sorry for the delay I trust this addresses your concerns I hope this answers your points (ques- tions) I will be pleased to I will be happy to I wish to advise that (Leave it out.) I would appreciate it if please / would you please / could you please I would be grateful if please / would you please / could you please i.e. that is if so-and-so transpires if so-and-so happens in a timely manner as soon as possible in accordance with section 12 under section 12 in conjunction with with / together with in consideration of for / because of in excess of more than
92 Effective Writing Officious and Flowery Language (“Cop Speak”)
TABLE 17. Cop Speak to Plain English (Continued) in keeping with under in order to to in relation to about in respect of / to about in situ in place in spite of the fact that though / although in terms of in in the course of during in the event of if in the majority of cases in most cases in the vicinity of near in this regard (Leave it out.) in this respect (Leave it out.) in toto in total / altogether / all up in view of the fact that because inform you of / inform you that let you know inter alia among other things / among others is applicable applies is dependent on / upon depends on is located in is in it appears to be the case that it seems that it is considered that I think that / I believe that it is incumbent on you you should / you must / you need to it is my considered view that I think that / I believe that it should be noted that (Leave it out.) locate find / put / place location place manner way Messrs A and B Mr A and Mr B negligible amount of a little / a few notify you / me let you / me know notwithstanding despite / although obtain get occurred happened / took place owing to because of paradigm model per annum a year pertains to is about please be advised that (Leave it out.) please do not hesitate to contact me please contact (get in touch with) me predominantly mainly / mostly previous last / latest / earlier previously earlier prior to before pro tem for the time being
Effective Writing 93 Avoid Confusing or Ambiguous Text
TABLE 17. Cop Speak to Plain English (Continued) proceeded to (walk / drive) walked / drove (started to walk / drive) provide you with further information let you have / give you more information provided / providing if purchase buy pursuant to clause 12 under clause 12 rectify fix / correct / repair regarding about relating to about rendered made reply answer require need requirement need respond / response answer retain keep reveal show / tell review the matter look at the matter again should it be necessary if necessary Should you require further information, If you need more information, please get please do not hesitate to contact. . . . . in touch with . . . . (Or leave it out.) should you wish to if you want to / if you like significant amount of a lot of / much / many status quo as is / the existing state subsequent to After subsequently Later substantial amount of a lot of / much / many tacit understanding informal / unstated / understanding take the matter up with Bloggs contact Bloggs about the matter the delay (the mistake) is regretted I am sorry for the delay (the mistake) thereby because of this thus so / therefore transmit Send transpire Happen unable to Cannot undertake to do so-and-so will (must) do so-and-so upon on utilise use verify check / confirm via through / by way of viz namely whereas because whilst while with a view to to with due regard for (something) taking (something) into account with immediate effect straight away / immediately with reference to about
94 Effective Writing Acronyms and Abbreviations
TABLE 17. Cop Speak to Plain English (Continued) with regard to about with respect to about you may care to you might like to you will be required to you need to / you should / you must your letter of the 20th instant your letter of 20 May
Acronyms and Abbreviations
Acronyms are words which have been formed by joining the first letters of a set of other words. For example: • ANZAC (Australian New Zealand Army Corps) • QANTAS (Queensland and Northern Territory Air Services) • UNICEF (United Nations International Children’s Emergency Fund)
Acronyms that do not make a word are spelled out, for example: • ABC (Australian Broadcasting Commission) • AFP (Australian Federal Police) • RSL (Returned Servicemen’s League) • COD (Cash on Delivery)
Some acronyms that form ordinary nouns have become part of modern English, for example: laser light amplification by stimulated emission of radiation radar radio detection and ranging SWOT strengths, weaknesses, opportunities, threats (used in business assessments)
Abbreviations are shortened forms of words divided into two main types with dif- ferent punctuation rules: • Abbreviations. The first one or more letter of the full word, for example: • p. (page) • cont. (continued) • Rev (reverend) • vol. (volume) • Mon (Monday) Abbreviations have a full stop if they start with a lower case letter. • Contractions. Contractions start with the first letter of the word and end with the last letter, for example: • hcp (handicap) • Dr (Doctor) • Fr (Father) • rd (road)
Effective Writing 95 Avoid Confusing or Ambiguous Text
• fig (figure) • Mr (Mister) Contractions DO NOT have a full stop.
Avoid Acronyms and Abbreviations
The most common and irritating form of jargon is overuse of acronyms and abbre- viations. Ask readers what they dislike about any technical writing and they'll say jargon. Ask them to give you an example and they'll say: “All those abbreviations”.
DPI for dots per inch and DTP for desktop publishing have become common place and can be acceptable in certain conditions. Instead of CRA, camera-ready artwork would be better, even in the photography business. SC is an unnecessary shortened form for Spot Colour and UGD for User Guide Documentation is long winded for the word manual.
Acronym Rules
Use the acronym or abbreviation without explanation, if everyone knows it, for example, IBM, USA, ACT, BMW, PhD.
Note: avoid using an acronym or abbreviation if it's commonly understood as one term and you mean another. For example, do not use PC for politically correct or for Privy Council as most people think of it as meaning personal computer.
Use common sense. If the abbreviation is better in the shortened form and causes no problems for any of your readers, use it freely. For example, if you are writing a leaflet about Personal Equity Plans and the word Plans could either confuse or become tedious, it might be better to use the shortened form PEP.
When introducing an acronym, the usual practice is to spell it out in the first instance that it is used and enclose the acronym in brackets. Each time you do this you set a memory test for your reader, so it is best to avoid this practice unless it is absolutely necessary. For example: It is in the best interests of the United States (U.S.) of America (USA) to develop a Tax Plan (TP) that punishes neither America's Disadvantaged Working Class (ADWC) nor the Independently Wealthy (IW). It should come as no surprise that both the ADWC and IW would like to see a Tax Plan (TP) that includes Lower Tax Rates (LTR), but the demand for LTR must be balanced against the needs of the Taxpaying Public (TP). As a result, the current TP should be eliminated.
Use your spelling checker to find acronyms and abbreviations - it's a constant reminder you may be overusing them. If you want to find the ones used in your organisation, look at the added dictionaries on your word processor.
Remember that using abbreviations and acronyms can go dreadfully wrong in the reader's mind. In the United Kingdom, there's an acronym in common use called PMT for pre-menstrual tension - the United States equivalent is pre-men- strual syndrome. According to ACTEW-AGL, PMS means Pole-Mounted Trans- former.
An Example of out-of-control acronyms: There is a Taxation Office team called the ABNICEPPPAYGIC team. ABN is the acronym for Australian Business Number and The PAYGI stands for
96 Effective Writing Acronyms and Abbreviations
Pay As You Go (Instalments) so the acronym was shortened to AICE PPPI. This stands for - ABN Integrity and Cash Economy Practices and Procedures PAYGI.' [From an anonymous tax office employee who won the contest to re-name the team ERIC].
Business Acronyms to Avoid
The following table lists acronyms used in the workplace that should be avoided. Not everyone knows what they mean.
TABLE 18. Business Acronyms AFTO Ask For The Order AIDA Attention, Interest, Desire, Action. AKA Also Known As AKUTA A Kick Up The Arse AWOL Absent Without Leave BAB Benefits Are Better BAU Business As Usual BIBOYS Boss Is Back on Your Site BID Break It Down BMT Before My Time BOGOFF Buy One Get One For Free BUNDY But Unfortunately Not Dead Yet CARE Crap And Really Expensive CLM Career Limiting Move. CRAFT Can’t Remember a Thing DAB Dead And Buried DEAD Delegate - Exhausted And Dead DIN Do It Now DINKY Double Income No Kids Yet DIY Deliver It Yesterday DOB Dirt On Boss DTS Danger To Shipping EBITDA Earnings Before Interest, Taxes, Depreciation and Amortisation E&OE Errors & Omissions Excepted EP Economic Profit FAB Features Advantages Benefits FAO For Attention Of FAT Final Acceptance Testing FBO Failing Better Offer FEAR Forget Everything And Run FIFO Fly In Fly Out, First In First Out FOC Free Of Charge GAG Great And Good GEKIS Go Early - Kids In School GIGO Garbage In, Garbage Out GTTM Going Through The Motions IIP Investors In People
Effective Writing 97 Avoid Confusing or Ambiguous Text
TABLE 18. Business Acronyms (Continued) JAWS Just Another Wage Slave JUT Joined Up Thinking KISS Keep It Simple Stupid KPI Key Performance Indicators LAST Listen Advise Solve and Thanks LIAR Look Into All Results LIMP Lacking In Much Personality LOBNAH Lights On But Nobody’s At Home LOMBNI Loads Of Money But No Idea MBWAL Management By Walking About and Listening OTB Outside The Box PANNA Previous Applicants Need Not Apply PEST Political, Economic, Social and Technological PICNIC Problem In Chair, Not In Computer PPP Pause Poise and Presence. PUASU Put Up And Shut Up QUANGO Quasi Autonomous Non-Governmental Organization RAID Risks, Assumptions, Issues and Dependencies ROI Return On Investment SAYE Save As You Earn SEP Someone Else’s Problem SWOT Strengths Weaknesses Opportunities Threats TEAM Together Everyone Achieves More TIC Tongue In Cheek TICTAC Turnaway If Criticism, Take All Credit TINO There Is No Alternative. TIO Take It Offline TLA Three Letter Acronym TNIIT There’s No ‘I’ In Team. TNSTAAFL There’s No Such Thing As A Free Lunch TNT Thanks but No Thanks TOAD Take Ownership And Deliver TOIL Time Off In Lieu. TOM Target Operational Model TTFN Ta Ta For Now TWAIN Technology Without An Interesting Name USP Unique Selling Point WFH Working From Home WIIFM What’s In It For Me? WIT Works In Theory WOS Waste Of Space WTFP What’s the Point WYSIWYG What You See Is What You Get, pronounced ‘WHIZZYWIG’
98 Effective Writing Latin (and French)
Latin (and French)
Use English words rather than French or Latin terms. Most contemporary style guides support the replacement of Latin abbreviations with their English language translations.
The old fashioned Latin acronyms are exactly that - old fashioned. The language has been dead for centuries, learning institutions no longer support the teaching of Latin acronyms, so they should be allowed to die a natural death by leaving them out of your writing.
TABLE 19. Latin/French to English
Acronym English Translation ie Shortened form of id est: that is eg Shortened form of exempli gratia: for example NB Shortened form of Note Bene: Note well. Take Notice. Ad hoc for a particular purpose ad lib Shortwened form of ad libitum: Impromptu, fill up time, make up as you go along M.O Shortened form of modus operandi: the way in which some- thing is done Q.E.D Shortened form of quod erat demonstrandum: which was to be demonstrated per diem a day PA Shortened form of per annum: a year per capita literally “by the head”; for each person; individually sine qua non essential per se By itself bona fide genuine carte blanche Unrestricted power to act on one's own. raison d'être reason for pros and cons Shortend form of pro et contra. This is well established standard usage. The alternative is the much longer 'argu- ments for and against' De Facto in fact; in reality; often also, in all but name de rigueur Strictly required. coup de grâce Finishing blow. Ex Officio by virtue of one's office Fait Accompli, Literally, “an accomplished fact”. au fait Laissez faire Literally, “leave things alone”. prima facie (arising) at first sight, based on the first impression quid pro quo something for something - nothing in life is free. sic “thus” or “in such a manner” - roughly translated “I know that the spelling is wrong, but that was how it appeared in the source”. Sine qua non Indispensable condition or qualification; a pre-condition status quo The previous situation of affairs; an unchanged position. viz Shortened form of videre licet: namely; like this.
Effective Writing 99 Avoid Confusing or Ambiguous Text
TABLE 19. Latin/French to English ad nauseam Shortened form of Argumentum ad nauseam: To a sickening degree. a priori Based on theory rather than observation. “The fact that their house is in such disrepair suggests a priori that they are hav- ing financial difficulties.” bête noire Something or someone particularly disliked. “Talk of his promotion had become his bête noire, and he began to avoid his friends.” in situ Situated in the original or natural position. ipso facto By the fact itself. “The yellow pages, ipso facto, cannot be included in the best seller list.” nom de plume Pen name. inter alia Among other things, as well as
Per
“Per” is a Latin word often used to mean “by the,” as in 27 miles per gallon (mpg) or 100 kilometres per hour (kph). Whenever possible, substitute “a” or “an.”
For example: “at the rate of $7 an hour” “75 cents a litre”
Do not use “per” in the sense of “according to” or “in accordance with.”
Good: We are sending you samples as you requested. Poor: We are sending you samples per your request. am and pm
Two common abbreviations are a.m. (ante meridian, before noon) and p.m. (post meridian, after noon). These are always acceptable.
Note: By modern conventions, am and pm are not capitalised and have no full stops. b.c and a.d
Also common are the abbreviations b.c. and a.d., usually written in small capitals, for marking dates as before or after the birth of Christ. According to tradition, Rome was founded in 753 b.c. The emperor Vespasian died in a.d. 79. or The emperor Vespasian died in 79 a.d.
It is traditional, and recommended, to write a.d. before the date, but nowadays it is often written after.
Non-Christians who do not use the Christian calendar may prefer to use b.c.e. (before the common era) and c.e. (of the common era) instead. This is always acceptable: According to tradition, Rome was founded in 753 b.c.e.
100 Effective Writing Latin (and French)
The emperor Vespasian died in 79 c.e.
The rule about using Latin abbreviations is very simple: don't use them. It is a poor style of writing to have Latin abbreviations peppered throughout a page, especially when writers use them without being quite sure what they mean and without under- standing the correct way to punctuate them. For example, the recommended form is this: Several British universities were founded in the Victorian era; for exam- ple, the University of Manchester was established in 1851.
The following version is not wrong, but it is poor style: Several British universities were founded in the Victorian era; e.g., the University of Manchester was established in 1851.
But this next version is disastrously wrong, because the punctuation has been omit- ted: Several British universities were founded in the Victorian era e.g. the Uni- versity of Manchester was established in 1851.
Using a Latin abbreviation does not relieve you of the obligation of punctuating your sentence. Again, if you avoid Latin abbreviations, you won't get into this sort of trouble. etc
This is an abbreviation for the Latin phrase et cetera which translates to the English “and other things.”
The abbreviation etc. should never be used in formal writing. It is vague and sloppy and, when applied to people, rather offensive. For example, avoid this: Central Africa was explored by Livingstone, Stanley, Brazza, etc.
Instead, rewrite the sentence in a more explicit way: Central Africa was explored by Livingstone, Stanley and Brazza, among others. or: Central Africa was explored by several Europeans, including Livingstone, Stanley and Brazza.
It is pronounced ET SETRA, and not EK SETRA. It is incorrect to write ect. or e.t.c. Such poor English makes your writing look hopelessly illiterate. Avoid Latin abbreviations altogether, and you will not have these problems.
Latin Lawyer Speak
The spread of Plain English legislation has reached the legal fraternity. It is now lawful to write legal documents using plain English so that everyone (including magistrates) understands the message and interprets the meaning.correctly. a fortiori (ah-for-shee-oh-ree) Latin for "with even stronger reason." a priori assumption
Effective Writing 101 Avoid Confusing or Ambiguous Text
(ay pree or-ee) An assumption that is knowable without further need to prove or experience it. ab initio Latin for "from the beginning" -- for example, "the contract was void ab ini- tio." ad hoc (ad-hock) Latin shorthand meaning "for this purpose only." Thus, an ad hoc committee is formed for a specific purpose, usually to solve a particular prob- lem. caveat emptor Latin for "let the buyer beware." corpus delicti (core-pus dee-lick-tie) Latin for the "body of the crime." Used to describe physical evidence that a crime has been committed, such as the corpse of a murder victim or the charred frame of a torched building. ejusdem generis (ee-joose-dem gen-ris) adj. Latin for "of the same kind." Used to interpret stat- utes when a law lists classes of persons or things. For example, if a law refers to automobiles, trucks, tractors, motorcycles, and other motor-powered vehi- cles, a court might use ejusdem generis to hold that such vehicles would not include airplanes, because the list included only land-based transportation. et al. (et-ahl) Abbreviation for the Latin phrase "et alia," meaning "and others." ex officio (ex oh-fish-ee-oh) Latin for "from the office." Used when someone holds one position because of the authority he or she has from another position (such as being on a committee simply because one is president of the corporation). lex loci (lecks loh-see) Latin for the "law of the place." It means local law. seriatim Latin for one after another, as in a series. For example, issues or facts might be discussed seriatim (or "ad seriatim"), meaning one by one in order. viz "To wit" or "namely." Example: "There were several problems, viz: leaky roof, dangerous electrical system, and broken windows."
Latin Plurals
Use English plurals rather than Latin plurals. For example, the English plural of album is albums. In Latin, it is alba. Imagine someone saying ‘Let me show you my photograph alba’.
Cacti is the Latin plural of cactus, and some writers use it in English. Cactuses is the English plural. Dictionaries list both, and neither is right or wrong. However, while Latin plurals are not considered out of place in botany and other scientific fields, there’s no good reason why ordinary English should have to abide by the rules of Latin grammar. Let's face it, you are not going to use ani instead of anuses, are you?
The following is a list of some common words, originally derived from Latin, and their Latin and English plurals:
102 Effective Writing Clichés
• Fungus, fungi, funguses. • Apparatus, apparati,apparatuses • Campus,campi, campuses • Status, stati, statuses • Virus, viri, viruses • Radius, radii, radiuses
When writing at work, drop the Latin plural pedantry. For example, the word agenda was derived from Latin, meaning ‘things to be done’, so the Latin pedants would insist that agendas should not exist as a plural of agenda. For the rest of us, agenda has acquired a singular sense, as a list of items to be considered at a meet- ing. Ignore the pedants and just make English work for us. If we need a plural for agenda, then agendas is good enough.
The following words are often confusing because they have been changed in their transition from Latin to English. Most of these changes involve their plural forms. appendix The Latin plural of appendix is appendices, and this is still the form most commonly accepted for sections of a written work. In English, appendixes is also acceptable. formula The Latin plural of formula is formulae, and this is still the preferred form in physics and mathematics. In general English, formulas is acceptable. memorandum The Latin plural of memorandum is memoranda. In English, memoran- dums is acceptable. This also holds for referendums. stigma The Latin plural of stigma is stigmata. In English, stigmas is acceptable. octopus This is not a Latin word at all, so octopi is wrong. In English, octopuses is correct. The same applies to quorum. In English, the plural is quorums. Quorum is not a Latin noun.
Clichés
How do you identify and avoid clichés?
Clichés occur when we try to be descriptive. Is the phrase you're about to use one that you've heard frequently in casual conversation, newscasts, and advertising? If so, it is probably a cliché or on its way there.
Effective Writing 103 Avoid Confusing or Ambiguous Text
The following (incomplete) list is a sample of often over-used phrases that have lost their meaning and are usually inappropriate: all walks of life patience of Job leaps and bounds fall on deaf ears behind the eight ball paying the piper leave no stone unturned from time immemorial bitter end sands of time lock, stock, and barrel give the devil his due calm before the storm selling like hot cakes long arm of the law hook, line, and sinker chequered career stick out like a sore thumb march of history by hook or by crook chomping at the bit whirlwind tour never a dull moment in the nick of time cool as a cucumber winds of change nipped in the bud in the same boat cry over spilled milk writing on the wall take on board a quantum leap in the frame suck it and see at the cutting edge at this point in time when it comes to the crunch outside the box up and running put on the back burner the bottom line a whole new ball game the nitty gritty put on hold
Irritating Phrases
The following list describes irritating words and phrases, rather than worn-out cli- ches: • At the end of the day • Fairly unique • I personally • At this moment in time • With all due respect • Absolutely • It's a nightmare • 24/7 • It's not rocket science • Synergy • To be fair/honest • Going forward • Let’s face it • 110% • Touch base • In the pipeline
104 Effective Writing Repetition
Repetition
Avoid unnecessary repetition. One of the most common types of unnecessary repe- tition involves modifiers that repeat information given in the word modified. • small in size • completely eliminate • silver in color • maximize as much as possible
Unacceptable Currently, aircraft must be kept a minimum of at least three miles apart in the horizontal plane.
Improved Currently, aircraft must be kept a minimum of three miles apart in the horizontal plane.
Weak In 1928, Alexander Fleming discovered for the first time that Penicillum mold could kill Staphylococcus bacteria in petri dishes. Fleming named the lethal antibacterial chemical secreted by the deadly Penicillum mold, dubbing it “penicillin.”
Improved In 1928, Alexander Fleming discovered that Penicillum mold could kill Staphylococcus bacteria in petri dishes. He dubbed the lethal antibacterial chemical secreted by the mold “penicillin.”
Weak Ability to separate from water is an essential prerequisite for a hydraulic oil to be used in plant systems where contamination of the hydraulic sys- tem by water is likely to form sludge emulsions of oil and water. [There is much repetition of phrases and terms in this sentence.]
Improved Plants with hydraulic systems routinely exposed to water should use hydraulic oils that are immiscible with water.
Sexist Language
Sexist language is language that unnecessarily identifies gender. Regardless of whether the majority of your audience are male or female, don’t use masculine pro- nouns to refer to a general user or operator, for example: The Property Officer can transfer items from any person/location depend- ing on his security settings
A simple fix is to use the plural form, which is the same for masculine and femi- nine:
Effective Writing 105 Avoid Confusing or Ambiguous Text
Property Officers can transfer items from any person/location depending on their security settings. You can transfer items from any person/location depending on your secu- rity settings.
He/She, His/Her
Be careful about using constructions like his/her, she/he. Many readers find these awkward and distracting.
Titles
Rewrite Titles to be neutral, like this: • Fireman. Fireperson is awkward, but firefighter is not • Policeman. Policeperson sounds silly, but police officer sounds natural • Mailman. Mailperson seems awkward, postal worker does not • Cleaning woman. House cleaner, office cleaner, custodian are all preferable • Poetess. Poet can be either a woman or a man and does not sound as if a woman poet is so odd that she needs a special appellation
Misplaced Modifiers
Modifiers (only, just, nearly, barely) are single words, phrases, or clauses that appear next to the word or words they modify. As a rule, related words should be kept together. When they are not, the modifiers are said to be misplaced.
For example, the sentence, “I saw a boy running down the street,” indicates that the “boy” was doing the running. However, if we wrote, “Running down the street, I saw the boy,” we would be suggesting to readers that “I” was doing the running.
Rule 1: The descriptive part of a sentence must have a clear link to its modifier.
Keep your modifier as close as possible to the part of the sentence that it modifies. They can be funny, but can also get you into trouble!
106 Effective Writing Misplaced Modifiers
Consider these: . The robber was described as a tall The robber was described as a man with a black moustache tall man weighing 150 pounds weighing 150 pounds with a black moustache
“150 pounds” describes the man, not the moustache
Consider this: Our church has a preschool program now; those who have children and don't know about it should see Rev. Smith after services today.
Revised: Those parents who have not yet heard about the church's preschool pro- gram should see Rev. Smith after services today.
You may prefer the originals! It can be enormous fun to purposefully create these types of sentences, but they are guaranteed to lose points when your managers and peers spot them in published documents. Avoiding this problem is easy: think about what the descriptive part of a sentence describes, and be sure the link is clear. Now find and fix misplaced modifiers in these sentences: The clerk handed the groceries to the customer in a paper bag. Despite being a murderous cannibal, the professor noted that Dr. Hanni- bal Lecter is an appealing character in some respects. Vapid and trite, the reviewer spared no aspect of the failed play. Reading the magazine, her puppy sat on her lap.The woman was escorted by her husband wearing a black velvet gown. She waved at me as I left with her right hand.
You also need to watch the placement of modifiers such as almost, even, hardly, nearly, often, and only. During training, the marathon runner almost ran around the track twenty times. Hungry Bill nearly ate a whole box of party pies.
Effective Writing 107 Avoid Confusing or Ambiguous Text
In both sentences, the marathon runner “almost ran" and hungry Bill “nearly ate“. In other words, nothing happened! During training, the marathon runner ran around the track almost twenty times. Hungry Bill ate nearly a whole box of party pies.
Make sure you place your modifiers correctly. Your readers must be able to cor- rectly interpret what you are saying, but if you misplace your modifiers, they will read it the wrong way almost every time.
108 Effective Writing Mixing American, Australian and British English
Mixing American, Australian and British English
Be careful when writing documents for audiences that are mixed American/Aus- tralian/British. The following table lists examples of commonly used words that have different meanings for different audiences:
TABLE 20. Australian, British and American English Words Term Australian/British American Bill Invoice Paper money Coach Bus with of higher standard of Extracurricular sports teacher at a comfort school Aerial A radio antenna Of, in or from the air, as in aerial photography Beater Something or someone that beats Used car in very poor condition Billion (traditionally) a million millions Thousand million (109) (1012) (US: trillion) Blinkers Leather flaps on a bridle used to Lights on a car that indicate the restrict a horse's lateral vision direction about to be taken Boot Storage compartment of a car Footwear covering lower leg Braces Over-the-shoulder straps to support Devices for straightening teeth trousers Braces Support that steadies or strengthens Tertiary enclosing punctuation: { something else } Bureau A type of writing table A public office or government agency Carriage Railway coach Baby transport vehicle Catapult Small Y-shaped hand-held projec- To rise quickly tile weapon often used by children Check Examine for a particular purpose, a Mark used to denote 'correct', pattern of coloured squares, a request for payment, especially at warning given in chess a restaurant, cheque Chum Friend Waste products from fish process- ing (heads, tails, blood etc) often used for shark fishing Cob A type of bread roll The portion of a corn plant around which the kernels grow Collect To win a bet To gather together, to pick up, to pick up a person or thing, charged to the receiver (to " call collect") Concession Reduction in price (discount) for a Contracted service, as in conces- certain category of person sion stand (a counter, stand or area at public entertainment ven- ues where snacks and/or drinks are sold) Custodian A keeper or guardian of a person or One who cleans and maintains a thing building Depot A storehouse or depository A railroad station or bus terminal Diner One who dines A type of restaurant Drape To hang limply Curtain Earth Safety connection of an electrical The planet Earth, soil circuit (US: ground) Entrée Starter of a meal Main course of a meal
Effective Writing 109 Avoid Confusing or Ambiguous Text
TABLE 20. Australian, British and American English Words Fender A fire screen, a cushioning device The part of a car that frames a to protect the side of a boat or ship wheel well Full stop Punctuation mark used at the end Complete stop (as of traffic) of a sentence (US: period) Gas State of matter (gas), natural gas Gasoline (UK: petrol) Gyro Gyroscope A sandwich Hire To rent (as in a car) To employ, recruit Indicator Direction-indicator light on a vehi- One that indicates cle (US: turn signal) Lift Platform or cage moved vertically An elevation in mood, "I got a lift in a shaft to transport people and from that compliment goods to various floors in a build- ing (US: elevator) Lounge A room for relaxation and enter- A bar tainment in a house Marquee Large, open-sided tent installed Signage placed over the entrance outdoors for temporary functions to a hotel, theatre, or cinema Nickel The metallic element (Ni) 5 cent coin Peg A wooden or plastic device for fas- Throw (as in baseball) tening laundry on a clothesline (US: clothespin) Solicitor Lawyer who advises clients, repre- One that solicits (e g contribu- sents them in the lower courts tions to charity), an advertiser, a promoter Store Place for storage of items not Consumer retail establishment e g needed for immediate use grocery store, hardware store Torch Handheld device that emits light Commit an act of arson (US: flashlight) Wrench A sudden pull or twist A tool used for tightening nuts and bolts Zip (short for zip fastener) a fastening Zero device (US: zipper)
Archaic Words and Phrases
Avoid the use of archaic words and phrases.
There are some words that are classified as archaic that are no longer used in main- stream text, but they pop up now and again. The st words (whilst, amongst, amidst) are archaic, or Old English, and have faded into obscurity. Whilst means the same as while, amongst is the same as among and amidst is the same as amid. It is best practice (and more in line with Plain English) to use the newer form to avoid incon- sistencies.
Table 21, Archaic Words, on page 110 is a small list of archaic words that are past their due date to be phased out:
TABLE 21. Archaic Words
Archaic Modern Hence That’s why
110 Effective Writing Archaic Words and Phrases
TABLE 21. Archaic Words Thus “This way” or “Like this” Whence Where forthwith immediately heretofore until now mayhap perhaps nary not at all nigh almostoever, if ever whereinsoever in whatever respect or place whereof of what whosoever every one who
From the Australian Federal Police Style Guide for Communications Products: Archaic endings “Please avoid the use of archaic endings on prepositions like among and conjunctions like while. That means do not use amongst and whilst. No amount of argument on the shades of difference in meaning between while and whilst or among and amongst could possibly be convincing. Give up now.”
Effective Writing 111 Avoid Confusing or Ambiguous Text
112 Effective Writing CHAPTER 8 Poor English
Today’s education standards can arguably be said to have deteriorated to some degree, but poor English has plagued our society since English language pedants have been around. So is there such a thing as “poor English” or “bad English?” Our technological society has managed quite well with text-speak, ebonics and various forms of broken English spoken in ethnic communities. The worst English students are quite capable of being understood, so why the need for good grammar?
Yes. Two reasons. Professionalism and respect.
Bad communication standards can make an intelligent person appear stupid and our messages unclear. We should strive for high standards in English grammar and punctuation so that our messages arrive at the reader in a fashion that is clearly understood and without ambiguity. This is important in the workplace where docu- ments are read by people the author may not know, where the information in these documents is critical and where a degree of credibility is expected.
This section of the document deals with common occurrences of poor English. In almost all cases, it is a simple matter to correct these common mistakes by educa- tion and awareness. The following examples of Poor English are a small collection: • Poor Word Usage • Dangling comparatives and superlatives • Verbalised Nouns • Prepositions Placement • Eggcorns (speak and spell errors) • Mixed Metaphors • Common Misuse of Words
Poor Word Usage
Beware of poor English word usage. Do not use “being as,” “being as how,” and “being that.” • Incorrect: “Being as” he's such a great person, I thought he would be chosen.
Effective Writing 113 Poor English
• Incorrect: That is wrong, “being as how” we didn't know the question • Incorrect: “Being that” we get along, let us go to dinner.
You can correct these sentences by using “because,” “considering,” or “since.”
“Of” should never be used in place of “have.” • Correct: I should have done it. • Incorrect: I should of done it. • Avoid: A should’ve done it.
Try not to use the word “but” too often. When you write “but,” it sounds like you are saying you disagree. Instead, try using the word “and.” For example: Sounds like you disagree: “I understand your message, but I would like to give it more thought.” Sounds more positive: “I understand your message, and I will give it more thought.”
Dangling comparatives and superlatives
TABLE 22. Dangling Comparatives and Superlatives
Avoid dangling comparatives and The range of options in the comparison superlatives, such as: must be specified, for example: Omo gets your clothes cleaner. Omo gets your clothes cleaner than Rinso The voltage across the diode is smaller The voltage across the diode is smaller than the voltage across resistor R1
Verbalised Nouns
Avoid using nouns as verbs.
Avoid saying “He authored ...“, instead say “He wrote ...“.
Avoid using “obsoleted”, instead say “made obsolete”.
Avoid saying “Action this document”, instead say “Forward this document to…” '...the vehicle was surveilled to an intersection where the product was seized.' Queensland police officer, heard on ABC radio news, 19 November, 2004. The 'product' was ecstasy.
Prepositions Placement
“Never use a preposition to end a sentence with!”
A preposition is a word, like `with', `to', `by', `in', `into' or `from', which indicates the relationship between a noun (`naming word') and the rest of the sentence. Con-
114 Effective Writing Prepositions Placement
trary to the saying quoted above, these words should not be placed at the end of sentences. They can be placed earlier by using `which', `whom' or `where':
For example: He wanted to tear up the contract he had entered into. becomes: He wanted to tear up the contract [into] which he had entered.
For example: We went to the opera, but I didn't like the people we went with.
Becomes: We went to the opera, but I didn't like the people with whom we went.
For example: I don't know where I obtained it from.
Becomes: I don't know from where I obtained it.'
TABLE 23. Common Prepositions about above across after against around at before behind below beneath beside besides between beyond by down during except for from in inside into like near off of on out outside over since through throughout till to toward under up upon with because of by way of in addition to in front of in place of in regard to in spite of instead of on account of out of according to
Effective Writing 115 Poor English
116 Effective Writing Eggcorns
Eggcorns
Eggcorn: What American linguists have recently begun to refer to informally as spell-as-you-speak errors. For want of a better term, this kind of poor English has been around for a long time.
It comes from the story of an American woman who wrote egg corns when she meant acorns, since, in her dialect, the first vowels are identical; for example, beg is pronounced bayg. The following table lists some of the more common egg corns that we hear (and read) from time to time.
TABLE 24. Common Eggcorns
Eggcorn Correct cacoughany cacophony supposably supposedly nucular nuclear intrical integral centrifical centrifugal eardrop eavesdrop mute moot a posable opposable all goes well for.... augurs well for.... alterior motive ulterior motive beckoned call beck and call bold-faced lie bald faced lie buy your time bide your time come to turns with come to terms with deep seeded deep seated enact vengeance, extract vengeance exact vengeance explanation mark exclamation mark far gone conclusion foregone conclusion font of knowledge/wisdom fount of knowledge/wisdom for all intensive purposes for all intents and purposes gamefully employed gainfully employed in lame man’s terms in layman’s terms lack toast and tolerant lactose intolerant like a bowl in a china shop like a bull in a china shop slight of hand sleight of hand something or rather something or other take another tact take another tack tow the line toe the line wet one’s appetite whet one’s appetite worth your wild worth your while wreck havoc wreak havoc wreckless driving reckless driving sick as hell anemia sickle cell anemia upmost utmost
Effective Writing 117 TABLE 24. Common Eggcorns star craving mad stark raving mad flying collars flying colours much adieu much ado ballistic vinegar balsamic vinegar all of the sudden all of a sudden another words in other words all do respect all due respect in route enroute laundry mat laundromat mind of information mine of information
Mixed Metaphors
A metaphor is the expression of an understanding of one concept in terms of another concept. They are used in everyday language to give meaning to our speech or our text or to explain difficult concepts using familiar themes. For exam- ple, to understand time as a resource, one might write: Time is running out.
In order to describe anger in these examples, the fire metaphor is used: Your insincere apology just added fuel to the fire. After the argument, Dave was smoldering for days. That kindled my ire. Boy, am I burned up!
Another conventional metaphor represents a storm as an angry person performing actions such as lashing, raging, and calming down. For example: It was a violent storm. The sea was lashing the rocks. The angry waves calmed down as the dawn came. We had a raging storm last night.
Metaphors can be useful for describing difficult concepts, or for describing emo- tions or abstract details that are more difficult to explain using text than speech. However, it is confusing and ambiguous to mix metaphors, and will always result in the wrong message. For example: Milking the temp workers for all they were worth, the manager barked orders at them. The first image suggests cows; the second, dogs.
To be of any use in effective writing, metaphors MUST use elements that can be compared logically and consistently. For example: Her handwriting was more cryptic than a doctor’s prescription. Handwriting and Doctor’s prescription are logical elements. Unless we tighten our belts, we'll sink like a stone.
118 Effective Writing Mixed Metaphors
The belt and the stone do not logically compare.
Use metaphors sparingly, and don’t make these mistakes: We could stand here and talk until the cows turn blue. A loose tongue spoils the broth. It’s time to step up to the plate and lay your cards on the table. He’s burning the midnight oil from both ends. I'm sweating like a bullet. We're starting the sales event behind, so it's all hands on deck for an uphill battle. All oars in the water, and sound the charge! I think he's finally starting to connect the writing on the wall. Let's burn that bridge when we come to it. That's opened the floodgates to Pandora's box of worms. He's as dumb as a lark. It's hardly rocket surgery. Let dead dogs die. We've barely scratched the tip of the iceberg. You're holding a gun against my head over a barrel. (by a local councillor discussing road improvements) We've got to iron out this bottle-neck. Yes, he was terribly clumsy. Just like a Chinaman in a bull closet. That's the snag in the ointment! He's bitten off more of the bed than he can lie on. Like beating a dead one-trick pony with a ten foot pole. (After the repair of his brakes) Stops like a dime. (Almost profound) There's no business without show business. We've got the best of both sides of the coin. We've got to nip this in the bud right out of the gate. Never kick a good horse in the mouth. The job of any good educator is to find that spark of enlightenment and to water it well. I've got a bull by the tail with a leaky scrotum and if I quit bailing, it would gore me. Let's run it up the flagpole and see if it makes a splash. We don't want to lead them up the garden path and then pull it out from under them.
Effective Writing 119 120 Effective Writing Common Misuse of Words
Common Misuse of Words
There are many words and phrases in the English language that are used incorrectly or are consistently used in ways that major English dictionaries do not condone in any definition. The following list is a page index to definitions and uses of the most commonly misused words: a lot / alot / allot 123 a or an? 128 Abstract 82 Abstract 82 Active 72 Active Verbs 71 Active Verbs: 70 adverse / averse 123 affect / effect 123 All Ready vs Already 135 all right / alright 129 all together / altogether 129 Allusion vs Illusion 135 alone / lonely 123 alternately / alternatively 129 Altogether vs All Together 135 am and pm 98 any one / anyone 124 appendix 101 Ascent vs Assent 135 Assure, Ensure, Insure 126 b.c and a.d 98 been / gone 124 beside / besides 129 Between / Among 129 bimonthly / semi-monthly 129 bought / brought 124 Breath vs Breathe 135 Bring / Take 125 Brusque: 68 Capital vs Capitol 136 Cite vs Sight vs Site 136 complementary / complimentary 124 Complex Words 73 Compliment vs Complement 136 comprise / compose 130 Comprise 126 Concise 66 Concise 71 Concise (Who-Does-What) 71 concurrent / consecutive 130 connote / denote 130 Conscience vs Conscious 136 Considered as, Considered to be 127 convince / persuade 130 council / councillor / counsel / counsellor 130 councillor / counsellor 124 Data / Data 125 decent / descent 124 disassemble / dissemble 125 discreet / discrete 130
Effective Writing 121 disinterested / uninterested 130 Disk / Disc 129 Elicit vs Illicit 136 emigrant / immigrant 130 Eminent vs Immanent vs Imminent 136 Equally As 127 etc 99 Exact Same 127 Examples 70 Excessive Detail 64 farther / further 131 few / less 131 figuratively / literally 131 flammable / inflammable 131 flaunt / flout 131 For example: 70 foreword / forward 131 formula 101 founder / flounder 132 Fun with Un-words 146 good vs well 132 hanged / hung 132 He/She, His/Her 104 historic / historical 133 Home / Hone 126 Hopefully 127 I before e 126 Incedence/Incidents/Instances 133 Into / in to 128 Isolated “This” 128 Its vs It’s 137 laid / lain / lay 133 Lead vs Led 137 lend / loan 133 Lie vs Lay 137 lightening / lightning 133 Long Sentence 72 Long Sentence: 73 Lose vs Loose 137 memorandum 101 nonplussed 133 octopus 101 Padded 71 Padded 71 Passed vs Past 138 Passive 72 Passive Verbs 71 Passive Verbs: 69 penultimate 134 Per 98 percent / percentage 125 perspective / prospective 125 Positive: 68 Practice / practise 134 Precede vs Proceed 138 principal / principle 134 Quote vs Quotation 138 Recognise these “new words”? 144
122 Effective Writing Common Misuse of Words
Shorter Sentences 72 Shorter Sentences: 73 Simple Words 74 Sort / Sought 134 Specific 82 Specific 82 Specific 64 stationary / stationery 134 stigma 101 Supposed to vs Suppose 138 Taught vs Taut 138 Text Only Description: 78 Than vs Then 138 That and Which 127 The conjunction “or” 140 The Plural of Virus 141 Their vs There vs They’re 138 Through vs Threw vs Thorough vs Though vs Thru 139 Titles 104 To vs Too vs Two 139 Too General 64 Unorganised / Disorganised 125 venal / venial 135 wander vs wonder 139 Who vs Who vs Whom 140 who's / whose 135 Wordy 66
Effective Writing 123 124 Effective Writing adverse / averse
Adverse means unfavourable, contrary or hostile. Averse means having a strong feeling of opposition, antipathy, or repugnance. They sailed despite adverse weather conditions. He was averse to taking his medicine. Incorrect: He is not adverse to having a drink now and then. affect / effect
“Affect” is usually a verb, which means “to influence”, as in: Will bad grammar affect my grade? His loud humming was affecting my ability to concentrate
“Effect” is usually a noun, which means “result”, as in: cause and effect relationship The sound of the falling rain had a calming effect, nearly putting me to sleep. a lot / alot / allot
A lot, meaning a large amount or number of people or things, can be used to mod- ify a noun. For example:- “I need a lot of time to develop this web site.”
It can also be used as an adverb, meaning very much or very often. For example:- “I look a lot like my sister.”
It has become a common term in speech; and is increasingly used in writing.
Alot does not exist! There is no such word in the English language.
Allot is a verb, which means to give (especially a share of something) for a partic- ular purpose. For example: “We were allotted a desk each.” alone / lonely
Alone can be used as an adjective or adverb. Either use means without other people or on your own. For example: “He likes living alone.”
“I think we're alone now.” (that is, there are just the two of us here).
Lonely is an adjective which means you are unhappy because you are not with other people. For example: “The house feels lonely now that all the children have left home.”
Note - Just because you're alone, doesn't mean you're lonely.
Effective Writing 125 any one / anyone
Any one means any single person or thing out of a group of people or things. For example: I can recommend any one of the books on this site.
Anyone means any person. It is always written as one word. For example: Did anyone see that UFO? been / gone
Been is the past participle of be. Gone is the past participle of go.
Been describes completed visits: If you have been to England twice, you have travelled there and back twice. If you have gone to England, you have not yet returned. bought / brought
Bought is the past tense of the verb to buy. For example: “I bought a newspaper at the newsagents. “
Brought is the past tense of the verb to bring. For example: “She brought her homework to the lesson.”
There is an 'r' in brought and an 'r' in bring. They belong together. complementary / complimentary
Things or people that go together well are complementary. Complimentary refers to a free bonus gift item or giving someone a compliment. Orange and blue are complementary colours. Buy this computer and get a complimentary gift. Incorrect: Jane was very complimentary about your new home. councillor / counsellor
Councillor is a noun which means an elected member of a local government. For example: “He was elected to be a councillor in 1998."
Counsellor is a noun, which means someone who is trained to listen to people and give them advice about their problems. For example: “The student union now employs a counsellor to help students with both personal and work-related problems.” decent / descent
Decent is an adjective meaning socially acceptable or good. For example: Everyone should be entitled to a decent standard of living.
126 Effective Writing Descent is a noun which can mean a movement downwards, or your ancestry. For example: The plane began its final descent prior to landing. She found out that she was of Welsh descent.
Data / Data
The word data is plural. Therefore, one must say, for example: These data are.... If the singular is required, use “datum”, or say “this measurement”. It is important to distinguish data, which are always measured, from results of com- puter simulations or calculations. One is not necessarily more trustworthy than another, although many scientists and engineers seem to have more confidence in measurements than in computer calculations. The computer work may be described as a “model”, “calculation”, or a “simulation”. Do not refer to results of a computer simulation as either “observation(s)” or data. disassemble / dissemble
To disassemble means “to dismantle” (for example, to take a transmission apart to repair it); to dissemble means “to tell lies”. percent / percentage
Use the word “percent” with numbers; use “percentage” without using a number.
Examples: Over 20 percent of our gross profit came from previous sales. A large percentage of bachelors live in Bankstown. perspective / prospective
“Perspective” has several meanings. One meaning is concerned with a view, out- look, subjective evaluation of something such as “a short-range perspective.” Another meaning concerns seeing things in their true relationship such as “Let's keep our perspective.” “Prospective” has to do with something that is expected to happen or be such as “a prospective buyer.”
Bring / Take
“Bring” indicates motion toward the speaker. “Take” indicates motion away from the speaker. Bring the report with you for tomorrow's meeting. Take this letter to Barney when you see him. You may take my book with you if you will bring it back by Tuesday.
Unorganised / Disorganised
Disorganised is strong and disapproving; unorganised is mild and may be neutral. Disorganised - not properly planned and controlled; (of a person) unable to plan one's activities efficiently. Unorganised - not organised.
Effective Writing 127 Her desk and papers seemed unorganised (but she could find anything she needed in a moment). Her desk and papers were disorganised (and she could never lay her hands on what she needed).
Home / Hone
You “home” in on a target. You DO NOT “hone” in on a target! “Hone” means “to sharpen something” such as one’s professional skills.
Assure, Ensure, Insure
While ensure and insure are almost interchangeable in some cases, assure is very different from both. • Never use assure in the sense of “Assure that the wording is correct”; you can only assure somebody that it is correct. • Insuring is the business of an insurance company, that is, setting aside resources in case of a loss. • Ensure means make sure, as in “Ensure that this is done by Monday.”
I before e
Words spelled with “ie” or “ei”, where the sound is e, (long ee), are usually written using the “i” before “e” except after “c.” Examples are “believe” and “receive.” However, the following words are exceptions to the rule, and need to be memo- rised: • either • height • neither • neighbour • reign • weigh • freight • seize • weird • conscience • leisure • height
Comprise
Comprise means contain, not constitute. In other words, a zoo comprises animals – it is not comprised of them. It is always wrong to write comprised of.
From the Melbourne University Policies and Guidelines document comes the fol- lowing: The 50 points are flexible in composition and may be comprised of either four by 12.5 point subjects or two 25-point subjects. The Certificate pro- grams are comprised of subjects studied at the undergraduate level. [Victorian Government Department of Human Services, Policy, Planning and Funding document, makes no less than six iterations of the misuse of
128 Effective Writing the phrase “comprised of”, for example:] In 2003/06, Office for Children services are comprised of four Output Groups..... The Family and Community Support Output Group is comprised of the fol- lowing three Outputs
Only one correct use of the word “comprises” was found in the entire document: This is a separate Output Group that comprises.....
Considered as, Considered to be
Almost always useless. • Poor: “The Oxygen Sensor is considered as essential to the engine management system.” • Poor: “The Oxygen Sensor is considered to be essential to the engine manage- ment system.” • Better: “The Oxygen Sensor is considered essential to the engine management system.” • Best: The Oxygen Sensor is essential to the engine management system.”
Ask yourself whether the word considered does anything in the sentence - does it matter who is considering?
Equally As
Don't EVER write “equally as”. Something can be equally important, or it can be as important, but it can't be equally as important.
Hopefully
Hopefully means in a hopeful way, not I hope. Avoid hopefully in writing; use I hope, we hope, I would like, or, best of all, leave it out altogether.
Exact Same
On a lighter note: “Exact same” is a corpuscular phrase that should be used only when something is identical to something else. It is the opposite of “a whole nother.” EXAMPLE: “This is the exact same restaurant where Alma found finger- nails in her pie. They gave her a whole nother slice.”
That and Which
A meticulous writer distinguishes between that and which. use which, which is always preceded by a comma, when introducing nonessential information. use that, never preceded by a comma, when introducing essential information.
For example: Resistors, which often have pretty colour bands, are common elements in electronic circuits.
Effective Writing 129 In this example, “pretty colour bands” are irrelevant to the functioning of the cir- cuit or whether resistors are commonly used. A resistor that has smoke rising from it is in danger of failing.
Here, “that has smoke rising from it” identifies specific resistor(s) that are essential to the meaning of the sentence.
Isolated “This”
Avoid an isolated use of the word this, as in: This is discussed later.
Instead, add a word to specifically indicate what this refers to: • this feature • this circuit • this problem • this approach a or an?
The rule is simple: Use a if the first letter of the following word begins with a consonant when pro- nounced. Use an if the first letter of the following word begins with a vowel sound (a, e, i, o, u) when pronounced. If the following word is either an abbreviation or a number, then consider whether it begins with a vowel sound when pronounced: a UPS (UPS = “you pea ess”) an MOV (MOV = “em oh vee”) an RS-232 (RS = “are es”) a 1N4004 (1N = “wun en”) an 1800 V (1800= “ate teen hundred”)
Sometimes the first letter in a word is silent, so one then considers the second letter in the word following the article: an honor, an hour, an heir (heir = “air”)
Use ‘a’ with words beginning with the letter U which start with a Y consonant sound (university and utensil), for example a university and a utensil. If, however, the initial U has a vowel sound, the word is preceded by “an”: it’s an umpire, an umbrella, and an understanding.
Into / in to
Do not confuse “into” with “in to”. “Into” is a preposition that generally represents motion from outside to inside such as: “She walked into the building.”
“In to” is an adverb followed by a preposition or first word of an infinitive. “She went in to make an announcement.”
130 Effective Writing Between / Among
“Between” refers to two. “Among” is used for three or more. Examples: Divide the jelly beans between the two of you. Divide the profits among the three centres.
Disk / Disc
The word disk appears in the English language around the 17th century. The word disc appears 100 years later as the derivation of the Greek word discus. In the 19th century, disc became the conventional spelling for audio recordings made on a flat plate (the gramophone record). By the 20th century, disc was established as the British standard and disk was more popular in American-English for any flat, cir- cular shape. Regardless of the heritage, today’s computer jargon refers to the spell- ing thus:
When you write about magnetic storage devices, it’s a “Disk”: Floppy Disk, Hard Disk.
Optical storage devices are commonly referred to as a “Disc”: Compact Disc, Laser Disc.
Verdict: Use whatever form you like, but be consistent. all right / alright
Although alright is widely used, it is considered nonstandard English. As the American Heritage Dictionary notes, it's not “all right to use alright.” all together / altogether
All together is applied to people or things that are being treated as a group. “We put the pots and pans all together on the shelf.” All together is the form that must be used if the sentence can be reworded so that all and together are separated by other words: “We put all the pots and pans together on the shelf.” Altogether is used to mean entirely: “I am altogether pleased to be receiving this award.” alternately / alternatively
Alternately is an adverb that means in turn; one after the other: “We alternately spun the wheel in the game.” Alternatively is an adverb that means on the other hand; one or the other: “You can choose a large bookcase or, alternatively, you can buy two small ones.” beside / besides
Beside is a preposition that means next to: “Stand here beside me.” Besides is an adverb that means also: “Besides, I need to tell you about the new products my company offers.” bimonthly / semi-monthly
Bimonthly is an adjective that means every two months: “I brought the cake for the bimonthly office party.” Bimonthly is also a noun that means a publication issued every two months: “The company publishes several popular bimonthlies.” Semi-
Effective Writing 131 monthly is an adjective that means happening twice a month: “We have semi- monthly meetings on the 1st and the 15th.” comprise / compose
According to the traditional rule, the whole comprises the parts, and the parts com- pose the whole. Thus, the board comprises five members, whereas five members compose (or make up) the board. It is also correct to say that the board is composed (not comprised) of five members. concurrent / consecutive
Concurrent is an adjective that means simultaneous or happening at the same time as something else: “The concurrent strikes of several unions crippled the econ- omy.” Consecutive means successive or following one after the other: “The union called three consecutive strikes in one year.” connote / denote
Connote is a verb that means to imply or suggest: “The word ‘espionage’ connotes mystery and intrigue.” Denote is a verb that means to indicate or refer to specifi- cally: “The symbol for ‘pi’ denotes the number 3.14159.” convince / persuade
Strictly speaking, one convinces a person that something is true but persuades a person to do something. “Pointing out that I was overworked, my friends per- suaded [not convinced] me to take a vacation. Now that I'm relaxing on the beach with my book, I am convinced [not persuaded] that they were right.” Following this rule, convince should not be used with an infinitive. council / councillor / counsel / counsellor
A councillor is a member of a council, which is an assembly called together for dis- cussion or deliberation. A counsellor is one who gives counsel, which is advice or guidance. More specifically, a counsellor can be an attorney or a supervisor at camp. discreet / discrete
Discreet is an adjective that means prudent, circumspect, or modest: “Her discreet handling of the touchy situation put him at ease.” Discrete is an adjective that means separate or individually distinct: “Each company in the conglomerate oper- ates as a discrete entity.” disinterested / uninterested
Disinterested is an adjective that means unbiased or impartial: “We appealed to the disinterested mediator to facilitate the negotiations.” Uninterested is an adjective that means not interested or indifferent: “They seemed uninterested in our offer.” emigrant / immigrant
Emigrant is a noun that means one who leaves one's native country to settle in another: “The emigrants spent four weeks aboard ship before landing in Los Ange- les.” Immigrant is a noun that means one who enters and settles in a new country: “Most of the immigrants easily found jobs.” One emigrates from a place; one immigrates to another.
132 Effective Writing farther / further
Farther is an adjective and adverb that means to or at a more distant point: “We drove 50 miles today; tomorrow, we will travel 100 miles farther.” Further is an adjective and adverb that means to or at a greater extent or degree: “We won't be able to suggest a solution until we are further along in our evaluation of the prob- lem.” It can also mean in addition or moreover: “They stated further that they would not change the policy.” few / less
Few is an adjective that means small in number. It is used with countable objects: “This department has few employees.”
Less is an adjective that means small in amount or degree. It is used with objects of indivisible mass: “Which jar holds less water?”
RULE: Less has to do with how much. Fewer has to do with how many. figuratively / literally
Figuratively is an adverb that means metaphorically or symbolically: “Happening upon the shadowy figure, they figuratively jumped out of their shoes.” Literally is an adverb that means actually: “I'm not exaggerating when I say I literally fell off my chair.” It also means according to the exact meaning of the words: “I translated the Latin passage literally.” flammable / inflammable
These two words are actually synonyms, both meaning easily set on fire. The highly flammable (inflammable) fuel was stored safely in a specially built tank.
Use nonflammable to mean not flammable. flaunt / flout
To flaunt means to show off shamelessly: “Eager to flaunt her knowledge of a wide range of topics, Helene dreamed of appearing on a TV trivia show.”
To flout means to show scorn or contempt for: “Lewis disliked boarding school and took every opportunity to flout the house rules.” foreword / forward
Foreword is a noun that means an introductory note or preface: “In my foreword I explained my reasons for writing the book.”
Forward is an adjective or adverb that means toward the front: “I sat in the forward section of the bus.”
Effective Writing 133 “Please step forward when your name is called.”
Forward is also a verb that means to send on: “Forward the letter to the customer's new address.” founder / flounder
In its primary sense, founder means to sink below the surface of the water: “The ship foundered after colliding with an iceberg.”
By extension, founder means to fail utterly.
Flounder means to move about clumsily, or to act with confusion. A good synonym for flounder is blunder: “After floundering through the first half of the course, Amy finally passed with the help of a tutor.” good vs well
Good is an adjective. Use good when giving more information about a noun. For example: My dog Sam is very good. He's a good dog. She didn't speak very good English. Her English isn't very good.
Well is an adverb. Use well to give more information about a verb. For example: He usually behaves very well. She didn't speak English very well.
The exception to this can be when you talk about someone's health. For example: She wasn't a well woman. and when you describe sensations. For example: This pizza tastes/smells/ looks good.
If you say "You look good." It means they look attractive.
If you say "You look well." It means they look healthy. hanged / hung
Hanged is the past tense and past participle of hang when the meaning is to execute by suspending by the neck: “They hanged the prisoner for treason.” “The convicted killer was hanged at dawn.”
Hung is the past tense and participle of hang when the meaning is to suspend from above with no support from below: “I hung the painting on the wall.” “The painting was hung at a crooked angle.”
134 Effective Writing historic / historical
In general usage, historic refers to what is important in history, while historical applies more broadly to whatever existed in the past whether it was important or not: “a historic summit meeting between the prime ministers;” “historical buildings torn down in the redevelopment.”
Incedence/Incidents/Instances
Incidence most often refers to degree or extent of the occurrence of something: “The incidence of measles in Whitman County has dropped markedly since the vaccine has been provided free.”
Incidents, which is pronounced identically, is the plural of “incident,” meaning “occurrences”: “Police reported damage to three different schools in separate incidents last weekend”.
Instances (not “incidences”) are examples: “Semicolons are not required in the first three instances given in your query.”
Incidents can be used as instances only if someone is using them as examples. laid / lain / lay
Laid is the past tense and the past participle of the verb lay and not the past tense of lie. Lay is the past tense of the verb lie and lain is the past participle: “He laid his books down and lay down on the couch, where he has lain for an hour.” lend / loan
Although some people feel loan should only be used as a noun, lend and loan are both acceptable as verbs in standard English: “Can you lend (loan) me a dollar?” However, only lend should be used in figurative senses: “Will you lend me a hand?” lightening / lightning
Lightening is a verb that means to illuminate; lightning is a noun referring to the electrical charges the cause flashes of light during storms: “The lightning struck, lightening the sky.” nonplussed
Meaning perplexed or bewildered, nonplussed is very often thought to mean just the opposite - calm, unruffled, cool-as-a-cucumber. A common mistake is to think the word means not “plussed,” but no such word exists. Nonplussed originates from the Latin non (no) and plus (more, further), and means a state in which no more can be done - one is so perplexed that further action is impossible.
Effective Writing 135 “The lexicographer grew increasingly agitated and nonplussed by the fre- quency with which she noted the misuse of nonplussed.” penultimate
Meaning “next to last,” penultimate is often mistakenly used to mean “the very last,” or the ultimate: “The perfectionist was crestfallen when he was awarded the penultimate prize; the grand prize went to another.”
Practice / practise
Practice is a noun, practise is a verb. The spelling “practice” is commonly used for both, though the distinction is sometimes observed. “Practise” as a noun is, how- ever, always wrong. A doctor always has a “practice,” never a “practise.” “The only thing Dean didn't like about piano practice was practising his scales.”
Tip: A good way to determine whether to use practice or practise is to substitute advice or advise and see if it sounds right. principal / principle
Principal is a noun that means a person who holds a high position or plays an important role: “The school principal has 20 years of teaching experience.”
Principal is also an adjective that means chief or leading: “The necessity of moving to another city was the principal reason I turned down the job offer.”
Principle is a noun that means a rule or standard: “They refused to compromise their principles.”
Sort / Sought
Sort can be a noun; used to describe something, as in: “you can use a proverb as a sort of metaphor”
Sort can also be a verb: "You can sort the columns alphabetically”.
Sought is the past tense of the verb "to seek". If you were looking for something yesterday, you "sought" it. For example: “It took a while, but we finally sought a suitable location”. stationary / stationery
Stationary is an adjective that means fixed or unmoving: “They maneuvered around the stationary barrier in the road.”
Stationery is a noun that means writing materials:
136 Effective Writing “We printed the letters on company stationery.” venal / venial
Venal is an adjective that means corruptible; venial is an adjective that means a slight flaw or offense: “In the Catholic church, a venial sin is one that is minor and pardonable, whereas a mortal sin is a serious transgression involving more venal or depraved behavior.” who's / whose
Who's is the contraction of who is. Whose is the possessive form of who. “Who's going to figure out whose job it is to clean the stables?”
Allusion vs Illusion
ALLUSION-an indirect reference: The professor made an allusion to Virginia Woolf's work.
ILLUSION-a false perception of reality: They saw a mirage: that is a type of illusion one sees in the desert.
All Ready vs Already
ALL READY-prepared: Dinner was all ready when the guests arrived.
ALREADY-by this time: The turkey was already burned when the guests arrived.
Altogether vs All Together
ALTOGETHER-entirely Altogether, I thought that the student's presentation was well planned.
ALL TOGETHER-gathered, with everything in one place We were all together at the family reunion last spring.
Ascent vs Assent
ASCENT- climb The plane's ascent made my ears pop.
ASSENT-agreement The martian assented to undergo experiments.
Breath vs Breathe
BREATH-noun, air inhaled or exhaled You could see his breath in the cold air.
Effective Writing 137 BREATHE-verb, to inhale or exhale If you don't breathe, then you are dead.
Capital vs Capitol
CAPITAL - seat of government)
CAPITOL - building in which a legislative body meets)
Cite vs Sight vs Site
CITE-to quote or document: I cited ten quotes from the same author in my paper.
SIGHT-vision: The sight of the Australian flag arouses different emotions in different parts of the world.
SITE-position or place: The new office building was built on the site of a cemetery.
Compliment vs Complement
COMPLEMENT-noun, something that completes; verb, to complete: A nice dry white wine complements a seafood entree.
COMPLIMENT-noun, praise; verb, to praise: The professor complimented Betty on her proper use of a comma.
Conscience vs Conscious
CONSCIENCE-sense of right and wrong: The student's conscience kept him from cheating on the exam.
CONSCIOUS-awake: I was conscious when the burglar entered the house.
Elicit vs Illicit
ELICIT-to draw or bring out: The teacher elicited the correct response from the student.
ILLICIT-illegal: The Columbian drug lord was arrested for his illicit activities.
Eminent vs Immanent vs Imminent
EMINENT-famous, respected: The eminent podiatrist won the Physician of the Year award.
IMMANENT-inherent or intrinsic:
138 Effective Writing The meaning of the poem was immanent, and not easily recognized.
IMMINENT-ready to take place: A fight between my sister and me is imminent from the moment I enter my house.
Its vs It’s
ITS-of or belonging to it: The baby will scream as soon as its mother walks out of the room.
IT'S-contraction for it is: It's a beautiful day for the race.
Lead vs Led
LEAD-noun, a type of metal: Is that pipe made of lead?
LED-verb, past tense of the verb "to lead": She led the campers on an over-night hike.
Lie vs Lay
You lay down an object, but you lie down on the bed.
LIE-to lie down (a person or animal. hint: people can tell lies): I have a headache, so I'm going to lie down for a while. also lying, lay, has/have lain: The dog has lain in the shade all day; yesterday, the dog lay there for twelve hours.
LAY-to lay an object down.: "Lay down that gun, Bubba!" The sheriff demanded. The town lay at the foot of the mountain. also laying, laid, has/have laid: At that point, Bubba laid the gun on the ground.
Lose vs Loose
LOSE--verb, to misplace or not win: Mum glared at Mikey. "If you lose that new lunchbox, don't even think of coming home!"
LOOSE--noun, to not be tight; verb (rarely used)--to release: The burglar's pants were so loose that he was sure to lose the race with the cop chasing him. While awaiting trial, he was never set loose from jail because no one would post his bail.
Effective Writing 139 Passed vs Past
PASSED-verb, past tense of "to pass," to have moved: The cyclone passed through the tropical town quickly, but it caused great damage.
PAST-belonging to a former time or place: Who was the past president of Microsquish Computers? Go past the fire station and turn right.
Precede vs Proceed
PRECEDE-to come before: Pre-writing precedes the rough draft of good papers.
PROCEED-to go forward: He proceeded to pass back the failing grades on the exam.
Quote vs Quotation
QUOTE-verb, to cite: I would like to quote Monty Python in my next paper.
QUOTATION-noun, the act of citing: The book of famous quotations inspired us all.
Supposed to vs Suppose
SUPPOSED TO-correct form for "to be obligated to" or "presumed to" NOT "sup- pose to"
SUPPOSE-to guess or make a conjecture: Do you suppose we will get to the airport on time? When is our plane sup- posed to arrive? We are supposed to check our bags before we board, but I suppose we could do that at the curb and save time.
Taught vs Taut
TAUGHT - past tense of "teach"
TAUT - tight
Than vs Then
THAN-use with comparisons: I would rather go out to eat than eat at the dining hall.
THEN-at that time, or next: I studied for my exam for seven hours, and then I went to bed.
Their vs There vs They’re
THEIR-possessive form of they:
140 Effective Writing Their house is at the end of the block.
THERE-indicates location (hint: think of "here and there"): There goes my chance of winning the lottery!
THEY'RE-contraction for "they are": They're in Europe for the summer--again!
Through vs Threw vs Thorough vs Though vs Thru
THROUGH-by means of; finished; into or out of: He ploughed right through the other team's defensive line.
THREW-past tense of throw: She threw away his love letters.
THOROUGH-careful or complete: John thoroughly cleaned his room; there was not even a speck of dust when he finished.
THOUGH-however; nevertheless: He's really a sweetheart though he looks tough on the outside.
THRU-abbreviated slang for through; not appropriate in standard writing: We're thru for the day!
To vs Too vs Two
TO-toward: I went to the University of Canberra.
TOO-also, or excessively: He drank too many screwdrivers and was unable to drive home.
TWO-a number: Only two students did not turn in the assignment. wander vs wonder
Wander (v) means to travel aimlessly. For example: "I often wander through the woods, it helps me think."
Wonder (v) means to consider or question some issue. For example: "People often wonder whether I really run this website alone ."
Wonder (n) means the feeling aroused by something strange and surprising. For example: "The pyramids are a wonder to behold."
Effective Writing 141 Who vs Who vs Whom
WHO-used as a subject or as a subject complement: John is the man who can get the job done.
WHO-pronoun, referring to a person or persons: Jane wondered how Jack, who is so smart, could be having difficulties in Calculus.
WHOM-used as an object: Whom did Sarah choose as her replacement?
The conjunction “or”
There are two distinctly different meanings of the word or in the English language: the inclusive or, which is satisfied if at least one of the items in the or'ed list is true: "any one or more of the following: A, B, C, or D" "A or B, or both", "A and/or B" the exclusive or, which is satisfied if only one of the items in the or'ed list is true: "one, and only one, of the following: A, B, C, or D" "either A or B, but not both"
It is not uncommon to see the conjunction or contradict the definition when used in computing. This has resulted in the term being abused in general use. For example, imaging this sign on a shop door: “drinking or eating prohibited”
Does this sign mean that you can simultaneously eat and drink in the shop? Of course not!
Consider the following practical example: Suppose we want to write a sign for the shop door to prohibit any combination of drinking or eating. 1. no drinking or no eating 2. drinking and eating prohibited
Sentences (1) and (2) are equivalent if the or is the inclusive or and if we under- stand "prohibited" in (2) to mean "no (drinking and eating)". These sentences are not a correct expression of the desired meaning, as they allow a person to either (drink and not eat) or (eat and not drink). 3. no drinking and no eating 4. drinking or eating prohibited
Sentences (3) and (4) are equivalent if the or is the inclusive or and if we under- stand "prohibited" in (4) to mean "no (drinking or eating)". Sentences (3) and (4) are logically correct. However, some lawyers will read sentence (4) and tell you
142 Effective Writing that it is ok to both drink and eat in the shop, following their erroneous interpreta- tion that or is exclusive. Given the ambiguity of or in English, sentence (4) is vague. 5. You may not eat or drink in this shop.
Sentence (5) is logically correct if the not is distributed, to mean "not (eat or drink)". This sentence suffers from ambiguity about the scope of not, in addition to ambiguity about whether or is the exclusive or. 6. Neither eating nor drinking is permitted.
Sentence (6) is the preferred way of expressing this directive. It is both logically correct and difficult to misunderstand.
Remember this rule: “Either, OR, Neither, NOR”
The Plural of Virus
The plural of virus is neither viri nor virii, nor even vira nor virora. It is quite sim- ply viruses, irrespective of context. The Oxford English Dictionary lists viruses for the plural:
Etymology: a. L. virus slimy liquid, poison, offensive odour or taste. Hence also Fr., Sp., Pg. virus. b Pl. viruses. An infectious organism that is usu. submicroscopic, can mul- tiply only inside certain living host cells (in many cases causing disease) and is now understood to be a non-cellular structure lacking any intrinsic metabolism and usually comprising a DNA or RNA core inside a protein coat (see also quot. 1977). [ Formerly referred to as filterable viruses, their first distinguishing characteristic being the ability to pass through filters that retained bacteria. ]
The Cambridge Encyclopedia of the English Language also supports viruses as the plural of virus.
Effective Writing 143 Frequently Misspelled Words absence fiery neighbor address fluorescent nuclear advice foreign occasion all right government occurrence arctic grateful odyssey beginning guarantee piece believe harass pigeon bicycle height playwright broccoli humorous precede bureau independent prejudice calendar jealous privilege camaraderie jewelry pumpkin ceiling judgment raspberry cemetery ketchup receive changeable knowledge rhythm conscientious leisure sacrilegious conscious library science decease license scissors deceive maintenance separate definite mathematics sincerely descent mediocre special desperate millennium thorough device miniature through disastrous miscellaneous truly ecstasy mischievous until embarrass misspell Wednesday exercise mysterious weird fascinate necessary you're February
144 Effective Writing CHAPTER 9 Bad Writing Habits
When you combine cultural diversity, social apathy and limitless communication mediums, it is inevitable that bad writing habits will appear to some as quite nor- mal. In fact, even though these bad habits are obvious, most of us just ignore it. This promotes acceptance of a writing style that, at best, confuses people and, at worst, offends. More often than not, it simply means that the message is lost.
Bad writing habits are different from just plain bad grammar, or mis-use of words. The most common bad writing habits have evolved over a period of time because of the proliferation of the following: • Un-words • Americanised Words • Weasel Words
Un-words
Try to avoid words that do not exist when you write. If your spell-checker high- lights a word such as autoised, actioned, helpware or reocurring in your document, the chances are you're straying into the world of the jargon writer. Keep to words people understand or at least can look up in a standard dictionary - your readers will thank you for the effort.
Note: Reoccur is misused for recur. Notice the error in this schoolteacher's letter below to the editor of “The Boston Globe”:
“Reading your June 21 front-page article irritated a reocurring wound.” This is incorrect. Use “recurring” because there is no such word as “reoc- curring” or “reoccurrence”. The correct words are “recur” and “recur- rence”.
Effective Writing 145 Bad Writing Habits
Avoid these un-words:
autoised incentivizing
billocked jointery
bloatware rebranding
custodied subjectlets
impactful trilemma
agreeance vaporware
The following un-words are dangerously close to becoming legitimate. Don’t let this happen! • Deplane, debark, detrain – only in America! These words are now in the Amer- ican Heritage Dictionary. • Doneness. An un-word widely used instead of “baking time”, “state of cook- ing” or “completion”. “Cooking times and temperatures vary with the method of preparation used, the size and shape of the Certified Angus Beef cut and the desired degree of doneness.” http://www.certifiedangusbeef.com • Irregardless. Not a word. Somewhere between Irrespective and Regardless. Use one of these. • Doable. Anything doable is feasible. Doable is not a real word, so use feasible.
Recognise these “new words”?
AUTO “DENTIST”, n. One who repairs dents, hail damage, and other types of minor damage on automobiles. [“dentist” to mean “one who repairs dents.”]
Context and source: “Auto 'dentist' specialising in dents, dings, and hail damage; high quality, affordable rates”, advertisement painted on the auto dentist's car (used by persons associated with car body repair).
146 Effective Writing Un-words
BAGGRAVATION, n. A feeling of annoyance and anger one endures at the airport when their bags have not arrived at the baggage carousel but everyone else's bags have [blend formed from words bag and aggravation].
BLADING, v. The act of rollerblading.
CARJACKING, n. An incident by which a usually armed individual coerces the driver of an automobile to give up the vehicle or drive it and the assailant to some specified location [blend of car and hijacking].
CORDS, n. A garment or article of clothing made of corduroy fabric. [Clipping of corduroy].
DETOX, n. A clinic or treatment facility at which substance abusers attempt to rid themselves of dependency on a particular drug.
EARWITNESS, n. An individual who hears an incident occur, especially one who later gives a report on what he heard [blend of ear and eyewitness].
EMOTICON, n. A symbol, usually found in e-mail messages, made up of punctua- tion marks that resembles a human expression. [Blend of emotion and icon].
FLAME, v. A personal attack within a post on Usenet or email reply. [metaphorical extension of flame]
GINORMOUS- adj. extremely large [blend of gigantic and enormous].
LOSINGEST, adj. In last place, worst off, lagging behind the rest [“losing”+ super- lative].
MALLRATS, n. Collective term used for pre-teens and teenagers for whom it is commonplace to spend large amount of time socializing and wandering through urban shopping malls [compound formed from roots mall and rat].
McJOB, n. A job in a service related field with low pay, low prestige and little opportunity for advancement [analogous word formed from prefix Mc- and job ].
NETIZEN, n. A person who spends an excessive amount of time on the Internet [blend of Internet and citizen].
POSTAL, adj. extremely hostile. [From the observation of postal workers going insane and killing fellow co-workers. Found most often in expressions go postal and get postal].
PROLLY, adv. Likely to happen, possibly occur. [Elided pronunciation of “proba- bly.” Assimilation of the “b”to an “l”]. Context and source: “I'm prolly going to the party tonight” (conversation).
ROAD RAGE, n. Aggressive driving habits often accompanied by dehumanization of other drivers and sometimes resulting in violence against other drivers.
SNAIL MAIL, n. The standard system of mail delivery in which letters, docu- ments, and packages are physically transported from one location to another, in contrast to electronic mail [rhyming compound formed from roots snail and mail].
SPAM, n. Multiple posts of the same message to the same or different email account. The message is usually advertising or marketing promotions and contains no useful or worthwhile information.
Effective Writing 147 Bad Writing Habits
SPORK, n. A utensil with both bowl and tines, a combination of spoon and fork. [Blend of spoon and fork].
TELEVANGELIST, n. An evangelist who conducts regular religious services on television. [Blend of television and evangelist].
Y2K, n. The year 2000. The problem in which some computer hardware and soft- ware are unable to process dates after 31 December 1999. [Acronym from Y (year) + 2 + K (Gr. 'kilos' thousand)].
Fun with Un-words • Thumbulate. To push harder on a button in hopes that that will revive a remote with dead batteries. • Nurge. To inch closer to a stoplight to make it change. • Onosecond. The period of time one spends between pressing the “send” button and then realising that they really shouldn’t have sent that e-mail message. • Quat. Past tense of the verb quit. • Remaindeer. Leftover venison. • Telecrastination. The act of always letting the phone ring at least twice before you pick it up. • Insparation. Thinking up a great idea while sitting in a spa. • Rignition. The embarrassing action of trying to start one's car with the engine already running. • Intaxication. Euphoria at getting a tax refund, which lasts until you realise it was your money to start with. • Kneebow. The elbow of one's leg. • Lactomangulation. When one manhandles the “open here” spout on a milk car- ton so badly that one has to resort to the “illegal” side. • Rememberful. Tending to, or likely to, remember. Opposite of forgetful. • Napjerk. The sudden convulsion of the body just as one is about to doze off. • Passhole. The idiot that drives too slowly in the fast lane. • Plothole. A rough spot in a storyline. • Pupkus. The moist residue left on a window after a dog presses its nose to it. • Gluke. To vigorously shake a sugar packet to settle the sugar so you can rip it open with out spilling it. • Ignisecond. The overlapping moment of time when the hand is locking the car door even as the brain is saying, “my keys are in there!“ • Tictactic. The technique used to extract a tic-tac from its container. • Inoculatte. To gulp down coffee quickly when you are running late. • Treeware. Printed documentation. • Melty. Of a melted consistency. The state of being partially melted. This term has been used in fast food commercials. • Rubbage. Large pieces of truck tyre found on the side of the road. • Trubbleyu. Three w; WWW, the prefix for most domain names. • Hangle. A cluster of tangled coat hangers. • Webshite. A poorly designed web site. • Vegeludes. Individual peas or kernels of corn that you end up chasing all over the plate.
148 Effective Writing Americanised Words
• Unfare. The flagfall of a Taxi fare. • Ediot. A person who, after giving you material to edit, continues to revise that same material without informing you. • Abdicake. To give up the last piece of cake to someone else. • Baldage. The accumulation of hair in the drain after showering. • Circumvaculate. To remain stationary while vacuuming in a circle around one- self. • Faxole. One who gets a new fax machine and insists on sending practice faxes to any friend with a fax machine. • Aquadextrous (ak wa deks' trus) adj. Possessing the ability to turn the bathtub faucet on and off with your toes. • Aqualibrium (ak wa lib' re um) n. The point where the stream of drinking foun- tain water is at its perfect height, thus relieving the drinker from (a) having to suck the nozzle, or (b) squirting himself in the eye (or ear). • Arachnoleptic Fit (n.) The frantic dance performed just after you've acciden- tally walked through a spider web.
Some un-words that seem to have made it into Technical Writing
Tabify, Untabify. These commands allow users to swap tabs for spaces or other characters in the captions editor.
Next versions: Uppercasify, Lowercasify, Indentify, Unindentify.
Uniqueify. Found in a Visual Studio presentation where it discusses creating unique names for projects when they get created. This is how it was used: “So after we uniqueify the project name...”
Winningest. From the ABC Lateline – “when you consider that he's the winnin- gest Test captain of all time”
Undefeateds. Headline in the Adelaide Advertiser at the height of the Australian Cricket team’s winning streak in 2003.
Complexify (from Creative Good Inc.) A quick, easy customer experience gar- nered Yahoo the success it enjoys today - and the new prominence of Yahoo Shop- ping complexifies the experience and could threaten Yahoo's core experience.
Objectify. From the CAA Project Meeting of 7 April 2005.
Americanised Words
Americanised forms of words such as “honor”, “labor”, “harbor” instead of the old fashioned “honour”, “labour”, “harbour” are perfectly acceptable. As an example of how we accept the “Americanisation” of some of our words, consider this article from the Canberra Times “Man winched from gorge after fall”, (December 19, 2009, p. 2): “.....teenagers who then dove blindly off the cliff“.
The lack of response to the use of the Americanised version of “dived” indicates that “dove” is gaining acceptance in Australian English. After all, it looks, and sounds, much neater than “dived”.
Effective Writing 149 Bad Writing Habits
Some of the reasoning behind the acceptance of some simplified forms of words stems from the double standards of Australian English as it applies to the deriva- tives of -our words. For example, “glamour” but “glamorous”, “humour” - “humor- ous”, “honour” - “honorary”, and so on.
Some people may protest that the adoption of American spelling will erode our national identity, but I don't think so.
See also Mixing American, Australian and British English on page 109.
Is Americanisation of Australian English a Real Threat?
Our greetings are increasingly American, like dropping the hullo (or the more Brit- ish hello), for Hi, and on parting have a nice day. Are we replacing our no worries for the American no sweat? Does it matter?
Our English doesn't sound American! When we speak, our Australian voice is slightly more raucous, it is understated. What about the Democrats' slogan “Keep the bastards honest” of a few years ago. Where else in the world could bastard be a masthead for a political party? Speaking of political figures…. [Gough Whitlam’s Address to the ACT Branch of the ALP in 1974] “I don't mind the Liberals, and still less do I mind the Country Party call- ing me a bastard. In some circumstances, I'm only doing my job if they do. But I hope you won't publicly call me a bastard as some bastards in the Caucus have”.
[and who could forget Gough Whitlam’s address after the dismissal….] “Well may we say 'God Save the Queen'; because nothing with save the Governor- General. The proclamation you have just heard was counter-signed 'Malcolm Fra- ser' - who will go down in history as 'Kerr's Cur'.”
When we think of Australian English, we think of people like John Clarke, Edna Everidge, Roy and H.G. We are internationally famous for these phrases: • flat out like a lizard drinking • rare as rocking-horse poo • mad as a cut snake • fair suck of the sav • blood’s worth bottling • to have tickets on yourself • ducks in the pond • more front than Myers and, more recently…. • straight to the pool room • to “do a bradley”.
We are famous for words like daks, ambo, fierie, pollies, acco, knackered, arvo, mozzie, sanga, ute, digger, furphy, bludger, dag, dob, dunnie, crook, sickie, tucker, whinge, yonks.
Aussie English is very distinct from the more ‘sanitised’ American English. If any one country is guilty of making words and phrases up, it’s us Australians, not the Americans!
150 Effective Writing Americanised Words
However, America is the origin of many words that we use every day, and most of us would never know that they were invented in America. The following is an incomplete list of words and phrases in our English language that originated in the USA: abolition classmate jackpot pull up stakes acronym cocktail jalopy punk aerobics codependency jazz ranch affirmative action cold feet Jeep revival airline cold war jelly-bean rip off alumnus commuter jukebox rock and roll alma mater cookbook keep the ball rolling rocket scientist artery cookie keno rodeo athlete's foot couch potato know-how role model baby-sit country club lengthy rowdy backlog cowboy levee scalp backpack credit card log cabin sexism backwoods cure-all logger shanty bandwagon cybernetics loony tunes shindig banjo D-Day macho showbiz barbecue deadhead mammoth sideburns barbershop deadline media sit-in bathtub downtown melting pot skyscraper belittle dude mileage slave driver biodegradable editorial millennium bug software blizzard envelope motel sound bite bloomers fan (mechanical movies spook bluejeans device) Ms. stenographer bluff fast food muckraker streak bogus filibuster multicultural streamline boss flunk Murphy's Law stud bottom line frontier mush suffrage brainstorm gangster newbie supermarket breeze geek nifty swamp brinkmanship gerrymander normalcy sweatshop buck gizmo OK swing voter bug goo paleface T-shirt bulldozer grass roots patent tar and feather bunkum gridlock PC teddy bear bust groovy peter out teenager caboose hamburger phony tomahawk cafeteria hello piker tornado canoe highbrow Pilgrim tote carpetbagger hijack pioneer UFO carpool hot dog plantation underprivileged caucus hotline pork barrel valedictorian cavort ice cream potato chip Venus fly-trap cereal immigrant pothole virtual reality Christmas tree IQ prairie wannabe clap board iron curtain progress warpath jackknife workaholic yuppie
Effective Writing 151 Bad Writing Habits
152 Effective Writing Weasel Words
Weasel Words
Weasel Words is an informal term for ambiguous analogies that lack substance and truth. They are used to create the illusion that the author is communicating legiti- mate information when, uponm closer inspection, the text has no substance at all. While the authors of this bastardised form of communication believe they are being clever, they only serve to confuse their audience.
Weasel Word Types
Weasel word usage can be divided into several categories:
Out of Context. Weasel Words are analogies that lose their meaning because they are used out of context. For example: Delegates will not only be shown how to develop and lead a superior, syn- ergistic enterprise to the new millennium but will also be introduced to “Elevation: the art, science and strategy of the radical profit leap” and ''Shoddipush: the deadly syndrome that white-ants most businesses.” Wareham Associates for a leaflet describing a one day seminar. The result appears to be a fragmented and uncoordinated approach that would efficiently be implemented by the heterodyning of these areas' out- puts through a strategic planning document. from a Government department discussion forum. “Heterodyne” is a radio frequency technology term. Radio frequency signals are combined to produce a new frequency equal to the sum or the difference between the originals.
Hide Adverse Evidence. Weasel words are used to draw attention away from adverse evidence: Dormantising. A term used by banks to cloud the issue of closing custom- ers' underutilised accounts without their knowledge. Unintended benefit leakage. Health industry speak for fraud by medical practitioners.
Manipulate an Audience. They are used intentionally to manipulate an audience by heightening audience expectations about the speaker's subject: Text speak. A mobile phone function which helps you to “reduce the number of messages sent”.
Hide the Truth. Weasel Words are used to make it difficult to verify the truth of a statement. This may be seen when a politician, for example, tries to alter the per- ception of an original speech after the speech has been given. For example: Performance Manage Out. Not happy with an employee? You don't sack, can, dismiss or fire them. You “performance manage them out of the enterprise”.
False Positives. A weasel phrase can be used to avoid criticism sounding negative, such as beginning an insult with the phrase, “With all due respect...” Off airport landing. A reference to describe an aircraft crash landing. Also see “friendly fire”. Deconditioned. Word used to describe ill patients in Victorian hospitals.
Effective Writing 153 Weasel Word Samples
People think that by creating words to use as anomalies, their audience will better understand the subject matter. This is NEVER true and is ALWAYS wrong. Using Weasel Words in this format only confuses people, because the words conjure up images in the minds of the audience that are true to their origins. 'This headline result was in line with expectations as we transition the business through its transformation program and commence implementa- tion of the new growth strategy. In a letter to shareholders from Coles Group Chairman. 'Know how to use the curriculum to facilitate cognitive and experiential learning as logical stimuli to surface the values involved. From the newsletter of the Australian Family Association in an article entitled 'STAR Program offers abstinence centred sexuality teaching for teens'. “Suggestions for enhancing synergies across seamless boundaries.” Notice on a suggestion box. Customer Sales Representative - Ref 0584 Managing ongoing business relationships with a select territory of existing customers will keep you challenged in this role as you make calls to cus- tomers to take product orders whilst cross selling and up-selling our prod- uct range. From Coca Cola Amatil add in SMH 'It's disappointing and we will be seeking other avenues to racecourse our development policy. Ballarat City Council general manager Workplace Refreshment Solutions Water coolers
Dangerous Weasel Words
Ask Please clarify with the client what the ask is. Request or question.
Bandwidth I’d love to help you with your project, but we just don’t have the band- width right now. Time or people.
Blue Ocean We need a blue ocean strategy; there are too many sharks in these waters. New, untouched market.
Blue-Sky Thinking Using your imagination.
Boil the Ocean Waste time.
Bottom Line
154 Effective Writing Weasel Words
An inclusive culture reduces turnover and improves productivity, innova- tion, and teamwork—all of which improve a company’s bottom line. Profitability; success.
Calendarize We need to calendarize another meeting to circle back on these action items. Schedule.
Content Creation Writing.
Contextualize Can you contextualize that for me? Explain.
Cradle-to-grave Complete; start to finish.
Cross-pollinate As each member of the region has certain products and services that can benefit the other members, we can effectively cross-pollinate best in class products and services across the region. Share ideas.
Deep Dive Focus on or explore details.
Dovetail The launch of this new annuity will dovetail nicely with our current project in which we sell overpriced mutual funds to the elderly and infirm. Fit together.
Download You Fill you in.
Drill Down Focus on or explore details. eCommerce Online sales.
End-to-End Complete; start to finish.
Engage Involve.
Human Capital Save on your expenditures by using your own human capital, which includes time, service, and talent.
Effective Writing 155 Often used to replace the words “people,” “employees,” or “skilled workers.”
Interface You must be able to interface with customers and other employees. Talk; communicate.
Knowledge Transfer Let’s make sure we’re on the same page to increase opportunities for col- laboration and knowledge transfer. Teaching, training, or learning.
Leverage Take advantage of, use, or act upon.
Negative Growth We’ve seen some negative growth in the mp3 player market since launch- ing our mobile device. Decline or loss, especially in sales.
Paradigm Model.
Paradigm Shift In order to overcome their current woes, Microsoft will need to undergo a paradigm shift. Change in perception or process.
Realize Negative Gains We want avoid the need to realize negative gains. Accept losses.
Resources People and/or money.
Solutioneering Thinking.
Strategic Partnership Working with another company.
Strategic Planning Planning.
Straw Man A crude plan or outline. A temporary idea or prototype.
Synergize We decided in our meeting to synergize with some marketing partners to increase sales. Work with others; cooperate.
156 Effective Writing Weasel Words
Synergy We are actualizing synergy amongst team members directly related to the project. Working together.
Take It Offline, Take This Offline That’s a great question, but let’s take it offline. Let’s talk about it later or privately.
Weasel Word Job Titles
Some people think that a grander job title is the same as a pay rise. Upgrading job titles is becoming more and more popular as employers try to keep their staff happy. • Space consultant (estate agent) • Ambient replenishment controllers (shelf stackers) • Revenue Protection Officer (ticket inspector) • Foot health gain facilitator (chiropodist) • Head of Verbal Communications (secretary) • Technical horticultural maintenance officer (gardener) • Flueologist (chimney sweep) • Dispatch services facilitator (post room worker) • Regional head of services, infrastructure and procurement (caretaker) • Knowledge navigator (teacher)
More Weasel Word Samples
The following sentences are extracts from real documents in the world of govern- ment, business, and education. They are not made up by the author. It requires too much hard work to write as badly as this.
TABLE 25. Weasel Word Samples and Translations
Weasel English Plain English Our company experienced a fourth-quarter Our company lost money in the fourth equity retreat. quarter. Two thousand employees underwent a We laid off two thousand employees. career alternative enhancement program. An intellectual property broker was Sydney City Council hired a public rela- engaged as a strategy to actualize greater tions expert to promote the city. positivism about the region. Let’s revisit that issue to align our end- Let’s come back to that problem later and state visions. see if we share the same goals for solving it. Cascade this to your people and see what Please inform your employees about this the push-back is. and see what they say. The soldier was discovered with a ballisti- The soldier was shot and killed. cally-induced aperture in the subcutaneous environment. He had experienced a termi- nal episode. An expenditure of $35 was initiated for a The Pentagon paid $35 for a hundred hundred wood interdental stimulators. toothpicks.
Effective Writing 157 TABLE 25. Weasel Word Samples and Translations Your son shows optimal positive emotive Your child enjoys playing with other chil- response to peer interaction during non- dren during recess. classroom recreational-agenda time peri- ods. Our fixed-wing aircraft visited and Our plane reached the target and dropped acquired the objective. There was minimal bombs on it. Few bombs fell where they incontinent ordnance and therefore accept- weren’t supposed to, and not too many able levels of collateral soft-target dam- innocent civilians were killed. age. Gridlock occurred due to failure of an There was a traffic jam because a stop electronically adjusted, color-coded vehic- light malfunctioned. ular-flow control mechanism. The Engineering Department experienced The Engineering Department has laid off advanced downward adjustments ten employees. Our company produces social-expression Hallmark makes greeting cards. products. Single-purpose agricultural structures can Pig farms can make a large area smell bad. generate geographically magnified olfac- tory stress.
158 Effective Writing CHAPTER 10 Memo Writing
A memo is a no-nonsense professional document, designed to be read quickly and passed along rapidly
Memos solve problems either by informing the reader about new information, like policy changes or price increases, or by persuading the reader to take an action, such as attend a meeting, use less paper, or change a current production procedure. Regardless of the specific goal, memos are most effective when they connect the purpose of the writer with the interests and needs of the reader.
Basic Memo Methods
Standard office memos can be approached in different ways to fit your purpose. Here are three basic methods: • The direct method, which is the most common, starts out by stating the most important points first and then moves to supporting details. This method is use- ful for routine information and for relaying news. • The indirect method makes an appeal or describes facts and arrives at a conclu- sion based on the facts. This method is best used when you need to arouse your reader's interest before describing some action that you want taken. • Balanced method. A combination approach. This method is particularly useful when relaying bad news, as it combines information and persuasion.
Memo Segments
The following are the accepted segments that make up a typical memo: • Heading (General Information) • Opening (Purpose) • Summary (Key Recommendations) • Discussion (Supporting Details) • Closing (Action) • Attachments (References and Detail)
Effective Writing 159 Memo Writing
Heading Segment
The heading segment follows this general format:
TO: (readers' names and job titles) FROM: (your name and job title) DATE: (complete and current date) SUBJECT: (what the memo is about, highlighted in some way)
Optional:
CC: (Carbon Copy)
BCC: (Blind Carbon Copy)
Although carbon copy paper is obsolete technology, the term persists. A blind copy might go to a person who should be informed of what is going on (such as a per- sonal assistant or a secretary), but who is otherwise not directly involved.
Address the reader by his or her correct name and job title, regardless of your rela- tionship.
Be specific and concise in your subject line. For example, “Problem” as a subject line could mean anything from a production problem to a personal frustration. Instead use something like, “Proposed Solution to Excessive Double Shifts on the Roster.”
Opening Segment
The purpose of a memo is usually found in the opening paragraphs and is presented in three parts: • the context and problem, • the specific assignment or task • the purpose of the memo
Answer the journalist's questions: who, what, when, where, and why.
The Problem
The context/problem is the event, circumstance, or background of the problem you are solving. Use a paragraph to establish the background and state the problem or simply the opening of a sentence, such as, “In our effort to reduce the incidents of double shifts....” Include only what your reader needs, but be sure it is clear. Be convincing, but don’t ramble on with insignificant details.
The Task
In the task statement, describe what you are doing to help solve the problem. If the action was requested, your task may be indicated by a sentence opening like, “You asked that I look at....” If you want to explain your intentions, you might say, “To determine the best method of controlling the number of double shifts, I will....”
If you are having trouble putting the task into words, consider whether you have clarified the Problem. You may need to do more planning before you're ready to write your memo.
160 Effective Writing The Purpose
State your reason for writing the memo and indicate what is in the rest of the memo. Be direct and come right out and tell your reader the kind of information that's in store. For example, you might say: “This memo presents a description of the current roster situation, some proposed alternatives to double shifts, and my recommendations.” If you plan to use headings for your memo segments, you can refer to your major headings in this forecast statement to provide a better guide for your reader. Divide the Purpose segment into the most important topics that the decision-maker needs.
Summary Segment
This segment provides a brief statement of the key recommendations you have reached. These will help your reader understand the key points of the memo imme- diately. This segment may also include references to methods and sources you have used in your research, but remember to keep it brief. In short, the Summary is a miniature version of the memo.
You can help your reader understand your memo better by using headings for the summary and the discussion segments that follow it. Try to write headings that are short but that clarify the content of the segment. For example, instead of using “Summary” for your heading, try “New Double Shift Minimisation Plan,” which is much more specific. The major headings you choose here are the ones that will appear in your purpose-statement forecast.
You may want to wait until after the report is drafted and all conclusions and rec- ommendations have been decided before writing the summary. If your memo is longer than a page, you may want to include a separate summary segment.
Discussion Segments
Memos are official documents, so your discussion section should include sufficient background information. The background may include the names and titles of the people involved, or the dates of earlier memos related to the one you are writing. The rest of the section should expand on and support all the points you made in your summary.
Include all the juicy details that support your ideas. Begin with the information that is most important, such as key findings or recommendations. Move to your specific or supporting facts. When including details, use the same format: strongest to weakest.
For easy reading, put important points or details into lists rather than paragraphs when possible.
Closing Segment
After the reader has absorbed all of your information, you want to close with a courteous ending that states what action you want your reader to take. Make it clear who should do what, and how long do they have to do it. Include alternatives in case your readers disagree with you. Be polite when you ask others to do work for you, especially if they are not under your supervision. Mention the actions that you plan to take next, and what your own deadlines are, so your reader can gauge how important the project is to you. Make sure you consider how the reader will benefit from the desired actions and how you can make those actions easier. For example, you might say, “I am at your disposal to discuss this recommendation
Effective Writing 161 Memo Writing
with you during our golf day. I shall endeavour to follow through on any decisions you make.”
Add a notation about what is attached below your closing, for example:
Attached: Several Complaints about Double Shifts, January - June 2004
Necessary Attachments
Make sure you document your findings or provide detailed information whenever necessary. You can do this by attaching lists, graphs or tables at the end of your memo. Be sure to refer to your attachments in your memo and add a notation about what is attached below your closing, for example:
Attached: Several Complaints about Double Shifts, January - June 2004
162 Effective Writing Case Study: The Importance of Effective Memo Writing
Case Study: The Importance of Effective Memo Writing
The following memo was written by engineers that designed the Three Mile Island nuclear power plant. The reactor was dedicated in September 1978, so when the memo was written, the inherent problem had already been detected. The disaster occurred in March 1979. Babcock and Wilcox Company Power Generation Group
To: B.A. Karrasch, Manager, Plant Integration From: D. F. Hallman, Manager, Plant Performance Services Cust. Date: August 3, 1978 Subj: Operator Interruption of High Pressure Infection (HPI)
References 1 and 2 (attached) recommend a change in B&W’s philosophy for HPI system use during low pressure transients. Basically, they recom- mend leaving the HPI pumps on, once HPI has been initiated, until it can be determined that the hot leg temperature is more than 50° F below Tpat for the RCS pressure. Nuclear Service believes this mode can cause the RCS (including the pres- suriser) to go solid. The pressuriser reliefs will lift, with a water surge through the discharge piping into the quench tank. We believe the following incidents should be evaluated: If the pressuriser goes solid with one or more HPI pumps continuing to operate, would there be a pressure spike before the reliefs open which could cause damage to the RCS? What damage would the water surge through the relief valve discharge piping and quench tanks cause? To date, Nuclear Service has not notified our operating plants to change HPI policy consistent with references 1 and 2 because of our above-stated questions. Yet, the references suggest the possibility of uncovering the core if present HPI policy is continued. We request that Integration resolve the issue of how the HPI system should be used. We are available to help as needed.
D. F. Hallman
DFH/feh attachments
Effective Writing 163 When you read through the memo, it’s clear that all the necessary parts are there, albeit a little unstructured. However, due to the nature of the memo, we should be able to answer the following questions: • What was the target audience (Experts, Technicians, Managers or Users)? • What is the problem? • How severe is the problem? • What is the solution?
Conclusion
This case study has been presented at several writing courses, and the following two conclusions are always the most compelling: • The Subject for the Heading of this memo is completely inappropriate, given the nature of the impending disaster. • This memo failed to put the Management into RED ALERT, which is what its purpose really is.
The engineers probably felt intimidated about bringing bad news, but they explained the situation technically. This message did not describe WHAT was wrong but what the consequences would be.
Excerpt from the report into the disaster: On March 28, 1979 at 4:00 AM, a minor malfunction occurred in the sys- tem which feeds water to the steam generators at the Three Mile Island (TMI) Unit 2 Nuclear Generating Station. During routine maintenance of the secondary side, feedwater to the steam generators was interrupted. The loss of feedwater caused the primary system to overheat causing the primary system pressure to increase. The reactor protective system scrammed the reactor but not before the system pressure caused one of the pressure regulating valves to open. This sequence of events was exactly what would be expected in such an event. Unfortunately, when the pressure in the reactor decreased, the valve failed to completely close resulting in a small break loss of coolant accident (SBLOCA). The emergency core cooling systems actuated as the system pressure continued to drop. Because of an incorrect interpretation of the instrument readings the operators terminated the operation of these sys- tems. This caused the core to eventually overheat. The fuel cladding rap- idly oxidized releasing hydrogen to the containment and further accelerating the process. Eventually, a significant portion of the fuel melted and flowed into the lower part of the core and lower reactor vessel head. This event led to the most serious commercial nuclear accident in US his- tory and fundamental changes in the way nuclear power plants were oper- ated and regulated.
A variety of studies have been unable to conclude that the accident had substantial health effects. The Radiation and Public Health Project, however, reported a spike in infant mortality in the downwind communities two years after the accident. Anecdotal evidence also records effects on the region's wildlife. For example, the fallout is alleged to have caused” a plague of death and disease among the wild ani- mals and farm livestock,” including a sharp fall in the reproductive rate of the region's horses and cows, reflected in statistics from Pennsylvania Department of Agriculture, though the Department denies a link to the radiation fallout.
164 Effective Writing Meeting Agenda and Minute Writing
Meeting Agenda and Minute Writing
Meetings are ineffective unless all participants know what they are trying to accomplish by having the meeting. This is an administrative responsibility. With- out good meeting minutes, participants waste the time spent in meetings because they may not remember or recognise: • What was decided in the meeting • What was accomplished in the meeting • What was agreed to in terms of the next steps (action items)
Agenda
The purpose of an agenda is bring harmony and efficiency to a meeting by restrain- ing participants from speaking out of context. If you are responsible for writing the meeting Agenda, the way that you write the agenda (and the subsequent Minutes) will assist participants in accomplishing their goals and retaining information given to them at the meeting. If at all possible, collaborate with the participants when writing the agenda. Ask participants to provide questions and issues for the agenda, then consult with the chairperson or executive before distributing the agenda.
Agenda Format
Use an easy to read font and leave plenty of white space for notes. The following content suggestions can be included depending on the type of meeting, the topics covered and the number of participants: • Heading: Date, time and title / purpose of the meeting. • Commencement time, conclusion time. • Numbered list of topics to be discussed and an estimate of the time to be allo- cated to each topic. • List of tasks for participants to complete or questions to be responded to at the meeting. • Schedule breaks (morning tea, lunch) • An Open or Questions item at the end of the meeting. Give participants time for feedback or to clarify information.
Minutes
If you are responsible for recording the minutes of a meeting, you are required to take notes during the meeting and to transfer those notes to a Minutes Document Template.
Like any document, the minutes must be reviewed before they are distributed. It is common practice for the chair or facilitator to review and approve the minutes.
Distribute the approved minutes as soon as practicable after the meeting.
Minutes Template
The format of a minutes document is a matter of preference. There is no hard and fast standard, but the recommendation is to have a template prepared to ensure con- sistency and user familiarity. Corporate markings and styles may need to be consid- ered, as minutes may become official documents for legal reasons.
Effective Writing 165 The following is a list of items that are considered essential information in most minutes. Prepare a template so that you can record the following: • Date/Time and Location of the meeting. • A list of participants and what team/business unit did they represent.
Tip: To be sure about who said what, make a map of the seating arrangement, and make sure to ask for introductions of unfamiliar people.
• If required, a list of invited participants who did not attend. • Items discussed, based on the Agenda. • Decisions made on each item. • Actions agreed upon for each item, who is to complete the actions and by when. • Materials distributed at the meeting and, if so, the location of copies or a link to the material. • Details of the next meeting, such as when, where and why.
Style Guide for Meeting Minutes
After the meeting, the notes need to be transferred to the Minute Template in a writing style similar to a Memo.
Tense. The present and future tenses are never used in the main text of minutes (although the present is used in cross-references - see above). This is because Min- utes are written from a point of view focusing on the meeting which is in the past, and all time references are relative to the point at which that meeting occurred.
Headings. Minutes need headings so that readers can skim for the information they need. Your template may include these:
Write in a positive manner. Avoid negative words such as no, not, won’t. Describe discussions as passionate, lively, or energetic, rather than heated or angry.
Appropriate Detail. Record topics discussed, decisions made, and action items. The only verbatim language required in meeting minutes is the precise wording of motions that were passed.
166 Effective Writing CHAPTER 11 Procedure Writing
Procedure writing, or writing instructions, is the backbone of technical writing. Pro- cedures are written as step-by-step explanations of how to do something: assemble something, operate something, repair something, or do routine maintenance on something. Poorly written procedures are infuriating, especially when there are only three fundamental rules for Procedure Writing: • Rule 1: Have a thorough understanding of the procedure in all its technical detail. • Rule 2: Use Plain English and simple words. • Rule 3: Test your instructions on the audience you wrote them for.
During the writing process: • Put yourself in the place of the person using your instructions. • Visualize the procedure in detail and transfer that awareness to your text.
Planning a Procedure Document
Step 1: Determine the structure or characteristics of the procedure you are going to write about.
Step 2: Define your audience. What is the level of familiarity with the topic?
Step 3: Define the Number of tasks. How many tasks there are in the procedure you are writing instructions for?
Procedures, Tasks and Steps
The procedure refers to a set of activities (steps) that make up your instructions. A task is a semi-independent group of steps within the procedure: for example, setting the clock on a video recorder is one task in the overall procedure of operating a video recorder.
Some instructions have only a single task, but have many steps within that task.
Effective Writing 167 Procedure Writing
When there are an excessive number of steps, the procedure can become daunting. It is far easier to group similar and related steps into multiple tasks and re-com- mence the numbering for the steps in each new task.
Types of Instructions
Instructions are either task-based or tools-based. Task-based instructions on using a phone-answering machine would have sections on recording your greeting, playing back your messages, saving your messages, forwarding your messages, deleting your messages.
Tools-based instructions on using a photocopier would have sections on the copy button, the cancel button, the enlarge/reduce button, the collate/staple button, the paper tray, the copy-size button, and so on.
Tools-based instructions can be difficult to get right. For example, the name of the button may not match the task it is associated with; what if you need to use more than just the one button to accomplish the task? Be careful when using tools-based instructions!
Sections of a Procedure Document
The following is a review of the sections you'll commonly find in procedures/ instructions. This is not a definitive list, nor do the sections need to be in the order shown here. These sections are only a guide.
Introduction. Introduce your procedures. The introduction should cover the fol- lowing points (not necessarily in this order): • Introduce each specific procedure by describing the scope of coverage. Make sure you include what won't be covered. • Write what your assumptions are in terms of your audience – what are the min- imum requirements of knowledge and background to understand the instruc- tions. • Describe what each procedure accomplishes. • Indicate the conditions when these instructions should (or should not) be used. • Give an overview of the contents of the instructions.
You may not need all of these elements, and some can be combined. The introduc- tion should be brief and to the point. Avoid long and laborious detail in the ele- ments of your introduction.
General warnings, cautions and notes. Instructions often include alerts to read- ers where the possibility exists of damage to persons and/or equipment. Instruc- tions also contain notes which emphasize key points or exceptions. It is often wise to include a list of these warnings in a separate section.
General and Technical Detail. It may be necessary to describe a level of technical detail related to the procedure. For certain instructions, this background is critical, otherwise the procedures make no sense.
Equipment and supplies. Most instructions include a list of the things the user requires before starting the procedure. This includes equipment, the tools you use in the procedure (for example, hammers, drills, keyboard, mouse) and supplies, the things that are consumed in the procedure (for example wood, paint, paper, toner).
168 Effective Writing Sections of a Procedure Document
In instructions, these are listed in a simple list. Use the two-column list if you need to add some specifications to some or all of the items, such as part numbers, brand names, sizes and amounts.
Steps
The actual writing of the steps requires the following considerations: • The structure and format of those steps • Supplementary information that might be needed • The point of view and general writing style
The First Step
The first step in a procedure must always be preceded by a short introduction. It can be as short as: “To open the case for editing, proceed as follows:” 1. Click File and choose Open.
Get To The Point
Writing effectively means the reader easily absorbs information, but procedure writing requires a no-nonsense, “get to the point” approach.
Avoid unnecessary introductory text to help readers immediately get the message.
Try to start the step with the verb that tells the reader what is happening. Leave the details to the body of the sentence. For example: Beginning with a clause: Using a 12mm adjustable spanner, connect the gas hose to the BBQ burners. Getting to the point: Connect the gas hose to the BBQ burners using a 12mm adjustable spanner.
Getting to the point means telling the reader what to do.
Types of Steps
Normally, steps in instructions are formatted as numbered lists. There are some variations, but steps are essentially written in the following formats:
Fixed-order steps. Refer Figure 3, Fixed Order Steps, on page 170. Fixed Order Steps must be performed in the order presented. For example, if you are changing
Effective Writing 169 Procedure Writing
the oil in a car, draining the oil is a step that must come before putting the new oil in. The format of these kinds of steps are in a vertically numbered list.
FIGURE 3. Fixed Order Steps
Variable-order steps. Refer Figure 4, Variable Order Steps, on page 170. Varia- ble Order Steps can be performed in any order. For example, some software trou- bleshooting guides tell you to check this or check that, depending on what you are trying to fix. You can do these kinds of steps in practically any order. With this type, the bulleted list is the appropriate format.
FIGURE 4. Variable Order Steps
Alternate steps. Refer Figure 5, Alternate Order Steps, on page 171. There may be two or more ways to accomplish the same thing. Alternate steps are used when var- ious conditions might exist. Use bulleted lists with this type, with OR inserted
170 Effective Writing Sections of a Procedure Document
between the alternatives, or the lead-in indicating that alternatives are about to be presented.
FIGURE 5. Alternate Order Steps
Nested steps. Refer Figure 6, Nested Steps, on page 171. When fixed order steps within a procedure become complex, you may need to break them down into sub- steps. In this case, you indent further and sequence the substeps as a, b, c, or, in extreme circumstances, as sub-sub-steps i. ii. iii. iv etc.
FIGURE 6. Nested Steps
Additional Information
It is often necessary to include additional information in the steps, such as the result of a step, the reason behind the procedure or some explanatory text to help the reader decide which step to do next. This is easy to do when writing an electronic document, as the author can make use of hyper-links or expanding text. On paper, however, it is easy to bury the steps in detail, to the point where the reader gets con- fused. In this case, use cross references to explanatory text elsewhere in the docu- ment or use footnotes where the text is minimal.
Effective Writing 171 Procedure Writing
Writing style
You should adopt a “real-world” style of writing instructions and make your instructions sound like instructions: “Press Pause on the front panel to stop the display temporarily” and “Click Save or Cancel.”
Adopt the following writing habits when writing instructions: • Use only the active voice. Your instructions and procedures are commands. “The Pause button should be depressed in order to stop the display temporar- ily.” Disregarding the Pause button's mental health, who is supposed to depress the button? See Active Voice on page 72. • Don’t use the word “please”. It makes a step sound optional. • Use a lot of “you.” That's entirely appropriate. You want to get in your reader's face and get their full attention. • Do not leave out articles: “Press Pause button on front panel to stop display of information temporarily” Avoid this stodgy, robotic style and include all arti- cles (a, an, the) and other such words that we'd normally use in instructions.
172 Effective Writing CHAPTER 12 Business Letter
The generic business letter is made up of the following blocks of text: • Date • Sender’s Address • Recipient’s Address • Salutation • Body • Closing • Enclosures
Date
The date line is used to indicate the date the letter was written. However, if your let- ter is completed over a number of days, use the date it was finished in the date line. Write out the month, day and year 5 cm from the top of the page. Depending which format you are using for your letter, either left justify the date or centre it horizon- tally.
Write the name of the month in full, the day in figures, and the complete year. For example: January 1, 2005 (NOT Jan.1, 2005 or January 1st. 2005)
DO NOT use the style 1/1/05 or’05 in the date line of a business letter.
Sender’s Address
Including the address of the sender is optional. If you choose to include it, place the address one line below the date. Do not write the sender’s name or title, as it is included in the letter’s closing. Include only the street address, city and post code. Another option is to include the sender’s address directly after the closing signature.
Recipient’s Address
The inside address is the recipient’s address. It is always best to write to a specific individual at the firm to which you are writing. If you do not have the person’s name, do some research by calling the company or speaking with employees from
Effective Writing 173 Business Letter
the company. Include a personal title such as Ms., Mrs., Mr., or Dr. Follow a woman’s preference in being addressed as Miss, Mrs., or Ms. If you are unsure of a woman’s preference in being addressed, use Ms. If there is a possibility that the person to whom you are writing is a Dr. or has some other title, use that title. Usu- ally, people will not mind being addressed by a higher title than they actually pos- sess. For international addresses, type the name of the country in all-capital letters on the last line. The inside address begins one line below the sender’s address or 2 cm below the date. It should be left justified, no matter which format you are using.
Salutation
Use the same name as the inside address, including the personal title. If you know the person and typically address them by their first name, it is acceptable to use only the first name in the salutation (that is, for example, Dear Lucy:). In all other cases, however, use the personal title and full name followed by a colon. Leave one line blank after the salutation.
If you don’t know a reader’s gender, use a non-sexist salutation, such as “To Whom it May Concern.” It is also acceptable to use the full name in a salutation if you cannot determine gender. For example, you might write Dear Chris Harmon: if you were unsure of Chris's gender.
Body
Single space and left justify each paragraph within the body of the letter. Leave a blank line between each paragraph. When writing a business letter, be careful to remember that conciseness is very important. In the first paragraph, consider a friendly opening and then a statement of the main point. The next paragraph should begin justifying the importance of the main point. In the next few paragraphs, con- tinue justification with background information and supporting details. The closing paragraph should restate the purpose of the letter and, in some cases, request some type of action.
Closing
The closing begins at the same horizontal point as your date and one line after the last body paragraph. Capitalize the first word only (for example, Thank you) and leave four lines between the closing and the sender’s name for a signature. If a colon follows the salutation, a comma should follow the closing; otherwise, there is no punctuation after the closing.
Enclosures
If you have enclosed any documents along with the letter, such as a resume, you indicate this simply by typing Enclosures one line below the closing. As an option, you may list the name of each document you are including in the envelope. For instance, if you have included many documents and need to ensure that the recipi- ent is aware of each document, it may be a good idea to list the names.
Typist initials
Typist initials are used to indicate the person who typed the letter. If you typed the letter yourself, omit the typist initials.
A note about format and font
Business letters are left justified and single spaced except for a double space between paragraphs. The generally accepted font is Times New Roman, size 12,
174 Effective Writing although other fonts such as Arial may be used if the correspondence is of a light, friendly nature. Traditionally, use a colon after the salutation (never a comma) and a comma after the closing, although the more modern format is to exclude the punctuation after the salutation and the closing.
Example:
March 16, 2005
Ernie English 1234 Northbourn Ave Canberra, ACT 2600
Dear Mr. English:
The first paragraph of a typical business letter is used to state the main point of the letter. Begin with a friendly opening; then quickly transition into the purpose of your letter. Use a couple of sentences to explain the purpose, but do not go in to detail until the next paragraph.
Beginning with the second paragraph, state the supporting details to justify your purpose. These may take the form of background information, statistics or first- hand accounts. A few short paragraphs within the body of the letter should be enough to support your reasoning.
Finally, in the closing paragraph, briefly restate your purpose and why it is impor- tant. If the purpose of your letter is employment related, consider ending your letter with your contact information. However, if the purpose is informational, think about closing with gratitude for the reader’s time.
Sincerely,
Choco Munday 55 Burnout Lane Jerrabomberra, NSW 2619
Effective Writing 175 Business Letter
176 Effective Writing CHAPTER 13 Document Review
Peer-reviewing (also called peer-editing) means people getting together to read, comment on, and recommend improvements on each other's work. Peer-reviewing is a good way to become a better writer because it provides experience in looking critically at writing.
Team-writing, or Collaborative Writing as its name indicates, means people getting together to plan, write, and revise writing projects as a group, or team.
The peer-reviewing process
Peer-review means to evaluate, criticise, and suggest improvements to another per- son’s written work. It is important that you communicate all of that to the writer. It may sound uncomfortable at first, but peer-reviewing is the most important phase of any document.
No document should be released or published without some form of peer review!
Make the process of peer review a part of the document life cycle. Include, as part of your document, peer-review notes on the writing assignment. Peer Review Notes should take the form of some introductory text and a Peer Review Check List. The introduction should include: • what your goals are • your concerns about your writing project • what kinds of things you were trying to do (topic, audience, purpose, situation, type) • alerts to any problems or concerns
Peer Review Checklist
The checklist should include, but not be limited to, some of the following: • Does the Table of Contents match the page numbers? • Are all the images referenced in the text? Do they add value or are they just “fill- ing”?
Effective Writing 177 Document Review
• Are all tables consistent in format and design? • Are all the topics/chapters relevant? • Is the style of writing consistent and appropriate? • Is the content interesting and thoughtful? • Is the main idea clearly stated? • Is there enough supporting information? • Are the supporting paragraphs relevant and well-organised? • Are the sentences clear? • Are sentence length and structure consistent? • Is the paper free of punctuation, spelling, and usage errors?
Some points on peer-reviewing someone’s work:
When you peer-review other people's writing, remember above all that you should consider all aspects of that writing, not just the grammar, spelling, and punctuation. The following are guidelines for critical review of another writer’s work: • It’s OK to provide criticism of a draft document, but try to suggest some way to address your criticism. You can’t just state that the document is “confusing” or the procedures are “not logical”. Explain how you would fix the problem. • Base your comments and criticisms on accepted guidelines, concepts, princi- ples, and rules. It's not enough to tell a writer that two paragraphs ought to be switched, for example. State the reason why: more general, introductory infor- mation should come first, for example. • The peer-review process is not an open invitation to re-write the document! Let the author of the document re-write it based on your suggestions and construc- tive criticism. • Make sure you acknowledge the areas in the draft that were done well, and then let the writer know about them.
Why Reviewing is Important
Here are some examples of writing where it is obvious that the writer did not bother with a review. [From the Louisville (Kentucky) Courier-Journal] The total number of births in the 1950s was larger than had ever been seen in the United States, but this was due mostly to the number of women having babies. [Flyer for a topic in the Lunch and Learn series at Auburn University, Ala- bama] "Disciplining Children: Concrete Helps" [Mark Purdy in the Lexington (Kentucky) Herald-Leader] In the USA's gallery of sports celebrities, Conner seems to fit in that curious category of competitors who are obsessed with winning to the point of obses- sion. [Several headlines appearing in some newspaper or other:] SQUAD HELPS DOG BITE VICTIM RED TAPE HOLDS UP NEW BRIDGE CHINK APPEARS IN GERMAN-JEWISH WALL NEW YORK PASSES TOUGH MEAT LAW [The Houston Chronicle, from Steve Sanderson, courtesy of Sara Chilton]
178 Effective Writing WOULD SHE CLIMB TO THE TOP OF MR. EVEREST AGAIN? ABSO- LUTELY!
FIGURE 7. Why Reviewing is Important
A Final Word on Document Review
Document projects in the workplace are as diverse as the audiences that read them. Technical Manuals, User Guides, Memos, Minutes of Meetings, Business Specifi- cations, Requests for Tender, Reports, and everything in between are documents that are found throughout corporate and Government enterprises.
As the author of any document, it is of the utmost importance that you never allow a document to leave your control until it has been reviewed.
Part of the review process is the Author Review. This is the process of reviewing your own work as you progress. As you re-read and revise your document, watch out for problems such as the following: • Make sure you provide real instructions; explanations of how to build, operate, or repair something. • Write a good introduction; in it, indicate the exact procedure to be explained and provide an overview of contents. • Make sure that you use the various types of lists wherever appropriate. In par- ticular, use numbered vertical lists for sequential steps. • Use headings to mark off all the main sections and subheadings for subsections. Remember that no heading Introduction is needed between the title and the first paragraph. • Use warnings, cautions and notes as appropriate. • Make sure you use the class style and format for all headings, lists, notes, and graphics. • Use graphics to illustrate any key actions or objects. • Provide additional supplementary explanation of the steps as necessary. • Remember to create a section listing equipment and supplies, if necessary.
Effective Writing 179 Document Review
• Include strong sections of definition, description, or both, as necessary. • Test your document with the intended readers. Show them the instructions and get them to carry them out. Then you should re-write areas where readers get confused or where they slow down. Readers should go from start to finish with- out stopping.
180 Effective Writing CHAPTER 14 How NOT To Write
[From UW Teaching Forum, published by the University of Wisconsin System Undergraduate Teaching Improvement Council] Operationally, teaching effectiveness is measured by assessing the levels of agreement between the perceptions of instructors and students on the rated ability of specific instructional behaviour attributes which were employed during course instruction. Due to the fact that instructors come from diverse backgrounds and occupy different positions within a given univer- sity, both individual and organisational based factors may contribute to the variance in levels of agreement between perceptions.
This is the kind of pseudo-scientific jargon, to which, unfortunately, educators are addicted. Don't let this happen to you! [Nature Conservation Regulation 1994 - 182 Additional restriction for licence for reptiles] '(2) in this section - “relevant person”, for a person, means a person who would be a relevant person for the person if the person were granted a commercial wildlife licence under this chapter.' [New South Wales Police Commissioner] 'We are committed to the ongoing professionalisation of our profession, believing this to be the best way of providing a strong policing service.' [Senator Amanda Vanstone] '...but perhaps one of the mistakes of the past is to go for shorter-term announceables, rather than long-term improvements.'. [STC Technology Ltd] 'There is an unavoidable conflict of terminology in naming the classes Class and Instantation. Instantation is not itself a real instance but a class (namely, the class of all real instances). Likewise, Class is not a class of real instances but a class of classes (namely, the class of all classes of real instances). Instantation could be renamed Class and Class renamed Type to avoid this. In that case, the members of Class would not be classes and the members of Type would not be types.' [Press release from a computer company] The integration of Microsoft Mail with HP DeskManager allows customers of HP DeskManager to migrate their desktops to Microsoft Windows while
Effective Writing 181 How NOT To Write
leveraging their existing investments in an enterprise-wide messaging backbone.
The following was written by D.G. Leahy in his 1996 book Foundation: Matter the Body Itself. Total presence breaks on the univocal predication of the exterior absolute the absolute existent (of that of which it is not possible to univocally predi- cate an outside, while the equivocal predication of the outside of the abso- lute exterior is possible of that of which the reality so predicated is not the reality, viz., of the dark/of the self, the identity of which is not outside the absolute identity of the outside, which is to say that the equivocal predica- tion of identity is possible of the self-identity which is not identity, while identity is univocally predicated of the limit to the darkness, of the limit of the reality of the self). This is the real exteriority of the absolute outside: the reality of the absolutely unconditioned absolute outside univocally predicated of the dark: the light univocally predicated of the darkness: the shining of the light univocally predicated of the limit of the darkness: actu- ality univocally predicated of the other of self-identity: existence univo- cally predicated of the absolutely unconditioned other of the self. The precision of the shining of the light breaking the dark is the other-identity of the light. The precision of the absolutely minimum transcendence of the dark is the light itself/the absolutely unconditioned exteriority of existence for the first time/the absolutely facial identity of existence/the proportion of the new creation sans depth/the light itself ex nihilo: the dark itself uni- vocally identified, i.e., not self-identity identity itself equivocally, not the dark itself equivocally, in “self-alienation,” not “self-identity, itself in self- alienation” “released” in and by “otherness,” and “actual other,” “itself,” not the abysmal inversion of the light, the reality of the darkness equivocally, absolute identity equivocally predicated of the self/selfhood equivocally predicated of the dark (the reality of this darkness the other- self-covering of identity which is the identification person-self). from an article by Professor Anna C. Chave, writing in Art Bulletin (December 1994): To this end, I must underline the phallicism endemic to the dialectics of penetration routinely deployed in descriptions of pictorial space and the operations of spectatorship.
The following is a single sentence from Roy Bhaskar’s Plato etc: The Problems of Philosophy and Their Resolution (Verso, 1994): 1 Indeed dialectical critical realism may be seen under the aspect of Foucauldian strategic reversal — of the unholy trinity of Parmenidean/ Platonic/Aristotelean provenance; of the Cartesian-Lockean-Humean- Kantian paradigm, of foundationalisms (in practice, fideistic foundation- alisms) and irrationalisms (in practice, capricious exercises of the will-to- power or some other ideologically and/or psycho-somatically buried source) new and old alike; of the primordial failing of western philosophy, ontological monovalence, and its close ally, the epistemic fallacy with its ontic dual; of the analytic problematic laid down by Plato, which Hegel served only to replicate in his actualist monovalent analytic reinstatement in transfigurative reconciling dialectical connection, while in his hubristic claims for absolute idealism he inaugurated the Comtean, Kierkegaardian
1. The jacket blurb, incidentally, informs us that this is the author’s “most accessible book to date.”
182 Effective Writing and Nietzschean eclipses of reason, replicating the fundaments of positiv- ism through its transmutation route to the superidealism of a Baudrillard.
The Longest Sentence in the World
[Read the following genuine sentence from a contract and study it carefully. See how the clauses have been put together, and how the writer has communicated their message. Make sure you always do the opposite!] In the event that the Purchaser defaults in the payment of any instalment of purchase price, taxes, insurance, interest, or the annual charge described elsewhere herein, or shall default in the performance of any other obliga- tions set forth in this Contract, the Seller may: at his option: (a) Declare immediately due and payable the entire unpaid balance of purchase price, with accrued interest, taxes, and annual charge, and demand full payment thereof, and enforce conveyance of the land by termination of the contract or according to the terms hereof, in which case the Purchaser shall also be liable to the Seller for reasonable attorney's fees for services rendered by any attorney on behalf of the Seller, or (b) sell said land and premises or any part thereof at public auction, in such manner, at such time and place, upon such terms and conditions, and upon such public notice as the Seller may deem best for the interest of all concerned, consisting of advertise- ment in a newspaper of general circulation in the county or city in which the security property is located at least once a week for Three (3) succes- sive weeks or for such period as applicable law may require and, in case of default of any purchaser, to re-sell with such postponement of sale or resale and upon such public notice thereof as the Seller may determine, and upon compliance by the Purchaser with the terms of sale, and upon judicial approval as may be required by law, convey said land and premises in fee simple to and at the cost of the Purchaser, who shall not be liable to see to the application of the purchase money; and from the pro- ceeds of the sale: First to pay all proper costs and charges, including but not limited to court costs, advertising expenses, auctioneer's allowance, the expenses, if any required to correct any irregularity in the title, pre- mium for Seller's bond, auditor's fee, attorney's fee, and all other expenses of sale occurred in and about the protection and execution of this contract, and all moneys advanced for taxes, assessments, insurance, and with interest thereon as provided herein, and all taxes due upon said land and premises at time of sale, and to retain as compensation a commission of five percent (5%) on the amount of said sale or sales; SECOND, to pay the whole amount then remaining unpaid of the principal of said contract, and interest thereon to date of payment, whether the same shall be due or not, it being understood and agreed that upon such sale before maturity of the contract the balance thereof shall be immediately due and payable; THIRD, to pay liens of record against the security property according to their priority of lien and to the extent that funds remaining in the hands of the Seller are available; and LAST, to pay the remainder of said proceeds, if any, to the vendor, his heirs, personals representatives, successors or assigns upon the delivery and surrender to the vendee of possession of the land and premises, less costs and excess of obtaining possession. [516 words]
Oldies but Goodies A writer must not shift your point of view. Also too, never, ever use repetitive redundancies. Also, always avoid annoying alliteration.
Effective Writing 183 How NOT To Write
Analogies in writing are like feathers on a snake. And don't start a sentence with a conjunction. Avoid clichés like the plague (they're old hat). Be more or less specific. Comparisons are as bad as clichés. Contractions aren't necessary and shouldn't be used. Do not be redundant; do not use more words than necessary; it's highly superfluous. Don’t over-use exclamation points!!!!! Eliminate commas, that are, not necessary. Parenthetical words however should be enclosed in commas. Eliminate quotations. As Ralph Waldo Emerson said, "I hate quotations. Tell me what you know.” Employ the vernacular. Eschew ampersands & abbreviations, etc. Everyone should be careful to use a singular pronoun with singular nouns in their writing. Exaggeration is a billion times worse than under-statement. Foreign words and phrases are not apropos. Go around the barn at high noon to avoid colloquialisms. If any word is improper at the end of a sentence, a linking verb is. If you reread your work, you can find on rereading a great deal of repeti- tion can be avoided by rereading and editing. If you've heard it once, you've heard it a thousand times: Resist hyperbole; not one writer in a million can use it correctly. It is wrong to ever split an infinitive. Never use a big word when a diminutive one would suffice. No sentence fragments. One should NEVER generalize. One-word sentences? Eliminate. Parenthetical remarks (however relevant) are (usually) unnecessary. Place pronouns as close as possible, especially in long sentences, as of 10 or more words, to their antecedents. Prepositions are not words to end sentences with. Puns are for children, not groan readers. Take the bull by the hand and avoid mixing metaphors. The passive voice is to be ignored. Understatement is always the absolute best way to put forth earth-shaking ideas. Use words correctly, irregardless of how others use them.
184 Effective Writing Who needs rhetorical questions? Writing carefully, dangling participles must be avoided. Verbs HAS to agree with their subjects. Proofread carefully to see if you any words out.
Terrible Analogies
He spoke with the wisdom that can only come from experience, like a guy who went blind because he looked at a solar eclipse without one of those boxes with a pinhole in it and now goes around the country speaking at high schools about the dangers of looking at a solar eclipse without one of those boxes with a pinhole in it.
She caught your eye like one of those pointy hook latches that used to dangle from screen doors and would fly up whenever you banged the door open again.
The little boat gently drifted across the pond exactly the way a bowling ball wouldn't.
McBride fell 12 stories, hitting the pavement like a garbage bag filled with vegeta- ble soup.
From the attic came an unearthly howl. The whole scene had an eerie, surreal qual- ity, like when you're on vacation in another city and "Jeopardy" comes on at 7 p.m. instead of 7:30.
Her hair glistened in the rain like nose hair after a sneeze.
Her eyes were like two brown circles with big black dots in the centre.
Bob was as perplexed as a hacker who means to access T:flw.quid55328.com\aaakk/ch@ung but gets T:\flw.quidaaakk/ch@ung by mis- take
Her vocabulary was as bad as, like, whatever.
He was as tall as a six-foot-three-inch tree.
The hailstones leaped from the pavement, just like maggots when you fry them in hot grease.
Her date was pleasant enough, but she knew that if her life was a movie this guy would be buried in the credits as something like "Second Tall Man."
Long separated by cruel fate, the star-crossed lovers raced across the grassy field toward each other like two freight trains, one having left Central Station at 6:36 p.m. travelling at 55 kph, the other from Strathfield at 4:19 p.m. at a speed of 50 kph.
The politician was gone but unnoticed, like the period after the Dr. on a Dr Pepper can.
They lived in a typical suburban neighbourhood with picket fences that resembled Nancy Kerrigan's teeth
John and Mary had never met. They were like two hummingbirds who had also never met.
Effective Writing 185 How NOT To Write
The thunder was ominous-sounding, much like the sound of a thin sheet of metal being shaken backstage during the storm scene in a play.
His thoughts tumbled in his head, making and breaking alliances like underpants in a dryer without Cling Free
The red brick wall was the colour of a brick-red crayon.
Her face was a perfect oval, like a circle that had its two sides gently compressed by a ThighMaster.
She had a deep, throaty, genuine laugh, like that sound a dog makes just before it throws up.
She grew on him like she was a colony of E. Coli, and he was room-temperature salami.
The revelation that his marriage of 30 years had disintegrated because of his wife’s infidelity came as a rude shock, like a surcharge at a formerly surcharge-free ATM.
The young fighter had a hungry look, the kind you get from not eating for a while.
He was as lame as a duck. Not the metaphorical lame duck, either, but a real duck that was actually lame, maybe from stepping on a land mine or something.
The ballerina rose gracefully en Pointe and extended one slender leg behind her, like a dog at a fire hydrant.
He was deeply in love. When she spoke, he thought he heard bells, as if she were a forklift backing up.
Shaking hands with him was like grabbing a sock full of pudding.
The day passed as slowly as a herd of turtles stampeding through peanut butter.
The eighth of November dawned much like any other day, except for August the fifteenth.
English Language Ambiguities
How I Met My Wife by Jack Winter Published July 25, 1994 in The New Yorker
It had been a rough day, so when I walked into the party I was very chalant, despite my efforts to appear gruntled and consolate.
I was furling my wieldy umbrella for the coat check when I saw her standing alone in a corner. She was a descript person, a woman in a state of total array. Her hair was kempt, her clothing shevelled, and she moved in a gainly way. I wanted des- perately to meet her, but I knew I'd have to make bones about it since I was travel- ling cognito.
Beknownst to me, the hostess, whom I could see both hide and hair of, was very proper, so it would be skin off my nose if anything bad happened. And even though I had only swerving loyalty to her, my manners couldn't be peccable.
186 Effective Writing Only toward and heard-of behaviour would do. Fortunately, the embarrassment that my maculate appearance might cause was evitable. There were two ways about it, but the chances that someone as flappable as I would be ept enough to become per- sona grata or a sung hero were slim.
I was, after all, something to sneeze at, someone you could easily hold a candle to, someone who usually aroused bridled passion. So I decided not to risk it.
But then, all at once, for some apparent reason, she looked in my direction and smiled in a way that I could make heads and tails of. I was plussed. It was concert- ing to see that she was communicado, and it nerved me that she was interested in a pareil like me, sight seen.
Normally, I had a domitable spirit, but, being corrigible, I felt capacitated as if this were something I was great shakes at, and forgot that I had succeeded in situations like this only a told number of times.
So, after a terminable delay, I acted with mitigated gall and made my way through the ruly crowd with strong givings. Nevertheless, since this was all new hat to me and I had no time to prepare a promptu speech, I was petuous.
Wanting to make only called-for remarks, I started talking about the hors d'oeu- vres, trying to abuse her of the notion that I was sipid, and perhaps even bunk a few myths about myself. She responded well, and I was mayed that she considered me a savoury character who was up to some good. She told me who she was. "What a perfect nomer," I said advertently.
The conversation became more and more choate, and we spoke at length to much avail. But I was defatigable, so I had to leave at a godly hour. I asked if she wanted to come with me. To my delight, she was committal.
We left the party together and have been together ever since. I have given her my love, and she has requited it.
THE PHAOMNNEAL PWEOR OF THE HMUAN MNID
I cdnuolt blveiee taht I cluod aulaclty uesdnatnrd waht I was rdgnieg. Aoccdrnig to a rscheearch at Cmabrigde Uinervtisy, it deosn't mttaer in waht oredr the ltteers in a wrod are, the olny iprmoatnt tihng is taht the frist and lsat ltteer be in the rghit pclae. The rset can be a taotl mses and you can sitll raed it wouthit a por- belm. Tihs is bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the wrod as a wlohe. Amzanig !
The Final Fixing of the Foolish Fugitive
[Originally composed by Rev. W. O. Taylor]
Feeling footloose, fancy-free and frisky, this feather-brained fellow finagled his fond father into forking over his fortune. Forthwith, he fled for foreign fields and frittered his farthings feasting fabulously with fair-weather friends. Finally, fleeced by those folly filled fellows and facing famine, he found himself a feed flinger in a filthy farm-lot. He fain would have filled his frame with foraged food from fodder fragments.
"Fooey! My father's flunkies fare far fancier," the frazzled fugitive fumed fever- ishly, frankly facing fact.
Effective Writing 187 How NOT To Write
Frustrated from failure and filled with forebodings, he fled for his family. Falling at his father's feet, he floundered forlornly. "Father, I have flunked and fruitlessly forfeited further family favours . . ."
But the faithful father, forestalling further flinching, frantically flagged his flunkies to fetch forth the finest fatling and fix a feast.
But the fugitive's fault finding frater , faithfully farming his father's fields for free, frowned at this fickle forgiveness of former falderal. His fury flashed, but fussing was futile.
His foresighted father figured, "Such filial fidelity is fine, but what forbids fervent festivities? The fugitive is found! Unfurl the flags! With fanfare flaring, let fun, frolic and frivolity flow freely, former failures forgotten and folly forsaken. For- giveness forms a firm foundation for future fortitude."
Little Red Riding Hood
At a previous but undetermined time-frame, a single-family domestic domicile was inhabited by a young girl, known as Little Red Riding Hood (LRRH), and her Maternal Parent (MP). The Maternal Parent (MP) had once provided for the fabri- cation of an article of clothing, a cloak in nature (including a "hood" or protective covering for the head of the wearer), that was RGB code [255,0,0] in hue (aka, "red"). As a result of this action, and the resultant repeated usage of the "hood", the young girl was always known as LRRH in substitution for the name identified on her birth certificate and other identifying documentation.
During one 24-hour interval, a request was issued by the MP for LRRH to deliver a package to the MP's Maternal Parent (MPMP) (genealogically identified as the Grandmaternal Unit (GU) with respects to LRRH). This package was to include: • cheesecakes • fresh butter • one dozen (12) strawberries
Little Red Riding Hood (LRRH) optioned to accept the Task Order (TO). LRRH further sourced a package delivery vehicle with the proper functionality for the Task Order, selecting a wicker basket. After a thorough and complete market sur- vey, leveraging LRRH's experience with similar Task Orders in the past, cheese- cake and fresh butter were acquired from the kitchen, whereas strawberries were acquired from the garden. While the latter item was not, strictly speaking, within the bounds of the Task Order, the marginal cost savings as compared to waiting for strawberries to grow in the kitchen appeared to be of great benefit to the MP in the completion of the Task.
With initial outsourcing complete, the journey was commenced by LRRH (see Appendix A: Proposed Map of Route Between the Domiciles of MP and GU). Dur- ing a brief eleventh-hour meeting, MP issued a contract rider requiring the com- plete confidentiality of all personnel working the Task Order. LRRH assured MP that there would be no violation of this rider.
In the course of executing the Task Order, LRRH was approached by market com- petitor Old Grey Wolf (OGW). There were inquiries from OGW to LRRH regard- ing the nature of the Task Order, and in violation of the contract rider, LRRH
188 Effective Writing disclosed sensitive and mission-critical data relating to the Task. Table 1-1 illus- trates the nature of the information believed to have been compromised:
TABLE 26. Information Compromised by LRRH During Interactions With GW
Nature of Data Disclosed To Severity of Disclosure Contents of Basket Old Grey Wolf Medium Nature of Task Old Grey Wolf High Destination of Journey Old Grey Wolf High
The identity of LRRH had been predetermined by OGW using standard practices of observation; therefore, that information was not compromised by the actions of LRRH.
It was the intent of OGW to compromise the functionality of LRRH, but the poten- tial negative impact on its operations by the nearby presence of an organized unit of fully-functional Wood Cutters (WC) provided for the redirection of its action item to the domicile of GU.
Though LRRH had blatantly violated the terms of the contract rider, this violation went unreported to supervisory entities (i.e., MP) by the violator. LRRH continued to action the Task Order despite clear and compelling evidence that the integrity of the process had been disenfranchised by the OGW.
While LRRH continued to analyze its processes through the implementation of the Task Order, OGW leveraged its greater cumulative experience and used Best Prac- tices to arrive at the GU client site in a more efficient and expedient manner than LRRH. Therein, the functionality of GU was impacted by the biorhythmic needs of OGW in a negative manner.
Upon the dissemination of information related to the pending closure of the Task Order assigned to LRRH, OGW engaged in an enterprise-wide analysis of situa- tional readiness. Determining that there were vulnerabilities in OGW's methodol- ogy, OGW elected to redesign the external identifiers of OGW to better emulate those of GU, by means of garbing the nightgown generally associated with GU and altering the vocal patterns of OGW to align with precedents set by GU.
After completing the Task Order by delivering the deliverables: • cheesecakes; • fresh butter; and • one dozen (12) strawberries
LRRH recorded observations of the host system. These observations included, but were not limited to: • My what big ears you have! • My what big eyes you have! • My what a big nose you have! • My what big teeth you have!
Upon receipt of the host system status analysis, OGW prepared and delivered a response regarding the functionality of the concerned functionalities, to include:
Effective Writing 189 How NOT To Write
• This functionality leverages the soundwaves generated from other sources, such as LRRH, to amplify the positive audio signal from such sources for the end user. • This functionality absorbs underutilized light emissions and their reflection from objects thereon, such as LRRH, to better provide for the identification of nearby entities by the end user. • This functionality analyzes the available transient atmospheric particles against a matrix of known particle cultures, such as LRRH, to provide near-instantane- ous and transparent supplemental feedback to the end user. • This functionality greatly impacts the capacity of the OGW to reprocess physi- cal assets related to LRRH in such a manner as to benefit the continued func- tional life-cycle of the OGW operations.
Immediately thereafter, Old Grey Wolf (OGW) executed its asset plan action item and severely compromised the functionality of Little Red Riding Hood (LRRH).
Nine Easy Steps to Longer Sentences
To illustrate, here’s a nice lampooning of good writing, stolen from the Internet:
Nine Easy Steps to Longer Sentences by Kathy McGinty
Are you tired of short, direct, and simple sentences that seem to take forever to fill up a page? Are you paid by the word? In either case you can benefit by increasing the number of words in your sentences and the bulk of your writing. And it's easy if you just follow nine simple steps, many of which you may already know and prac- tice.
To show how easily you can apply these steps, I'll start with the following ludi- crously short and simple sentence and increase its verbiage step by step. More night jobs would keep youths off the streets.
Step 1: Begin to lengthen your statement by referring to studies, even if you're not aware of any studies. After all, who really cares? And if anyone challenges you, you can protect yourself by weaselling (see Step 5). Studies have found that more night jobs would keep youths off the streets.
Step 2: Replace simple words like more, jobs, night, youths, and streets with multi- ple syllable words of Latin or Greek origin. Studies have found that additional nocturnal employment would keep adoles- cents off thoroughfares.
Step 3: Use sophisticated verbs, the vaguer the better. The verb found is much too clear and simple, whereas indicate, develop, and identify are excellent multi-pur- pose verbs with so many meanings that you can use them in almost any context to mean almost anything. What precisely does indicate mean, anyway? If you use identify or indicate, you can further lengthen your sentence by attaching the fact that to it. Studies have identified the fact that additional nocturnal employment would keep adolescents off thoroughfares.
190 Effective Writing Step 4: Rely on such adjectives as available, applicable, and appropriate to lengthen sentences without changing or adding any meaning. If possible, use vari- ous, one of the most meaningless of all the meaningless modifiers. Various available applicable studies have identified the fact that additional appropriate nocturnal employment would keep adolescents off thoroughfares.
Step 5: Use weasel words as often as possible. A number of is particularly useful because it can refer to any number at all: -9, 4.78, 0, 5 billion, you name it. (For more effective weaseling, replace wills and woulds with cans and coulds.) A number of various available applicable studies have generally identified the fact that additional appropriate nocturnal employment could usually keep ado- lescents off thoroughfares.
Step 6: Sprinkle your sentences with classic redundancies. A redundancy is simply saying the same thing twice. A number of various available applicable studies have generally identified the fact that additional appropriate nocturnal employment could usually keep juve- nile adolescents off thoroughfares.
Step 7: Add meaningless “it is” and “there is/are” expressions, not only to lengthen your sentences but also to give them a scholarly ring. There is no escaping the fact that it is considered very important to note that a number of various available applicable studies have generally identified the fact that additional appropriate nocturnal employment could usually keep juvenile adolescents off thoroughfares.
Step 8: For the precision that all good writing deserves, use legalisms, the more redundant the better. There is no escaping the fact that it is considered very important to note that a number of various available applicable studies have generally identified the fact that additional appropriate nocturnal employment could usually keep juvenile adolescents off thoroughfares, including but not limited to the time prior to midnight on weeknights and/or 2 a.m. on weekends.
Step 9: Use foreign words and phrases to lengthen and enliven your sentences. Especially apt are Latinisms and other obscurities whose meanings have long been forgotten if they were ever known. There is no escaping the fact that it is considered very important to note that a number of various available applicable studies ipso facto have generally iden- tified the fact that additional appropriate nocturnal employment could usually keep juvenile adolescents off thoroughfares during the night hours, including but not limited to the time prior to midnight on weeknights and/or 2 a.m. on weekends.
So there you have it. Following these nine steps, I've managed in no time to increase the number of words in my sentence nearly seven fold, well above the level of incomprehensibility. And best of all, I've accomplished this feat with little or no change in meaning.
Effective Writing 191 How NOT To Write
192 Effective Writing CHAPTER 15 Writing For Developers
Software developers are required to write important text early in the development phase as the UI is conceived and coded. This text is seen more frequently and by more people than perhaps any other type of technical writing.
Technical writers should always be included in the creation of error messages. At the very least, software developers capable of writing messages that make sense to the average person should be given the task.
Establish a policy within the development team for technical writing staff to review the application error messages during the beta cycle.
Users DO NOT carefully read text in an application module window or screen in a left-to-right, top-to-bottom order. They start by quickly scanning the whole window, then they read the text in roughly the following order: • Controls in the centre • The button labels • Other controls • Instructions • Window title • Other text and footnotes
Once users make a decision to proceed, they will stop reading and do it.
Error Messages, Prompts and Warnings
A good error message: • Clearly describes what is wrong. Before you write (or rewrite) the error mes- sage, consult the developer and get a description of all the possible situations that can cause the error. • Is in a user-readable language. “ERROR CODE: 23DD8? is meaningless to the user if this is all that is provided in the message.
Effective Writing 193 Writing For Developers
• Is polite and does not blame the user. Errors intimidate novice users, and although experts are more adept at blaming the important things (the System or the Manual), error messages MUST be written to ASSIST the user. • Gives advice on how to fix the problem. Error dialogue boxes have limited space for writing. Try not to describe the error at length and focus on what the user can do to fix the situation.
Clearly Describe What is Wrong
It is not always easy to provide this information. Quite often, the programming code generates a single message for multiple error conditions. It is up to the soft- ware developer to make the code a little more intelligent, and split different errors apart. For example, a networking router will generate a timeout error if the latency period on the network grows too large. It might generate the same error if someone trips over a network cable, or the cable is mistakenly pulled from its socket on the router. Whatever the cause, the router is unable to communicate with the network.
Providing the user with meaningful information in the error message becomes the developer’s responsibility.
FIGURE 8. Meaningless Error Message
In Figure 8, Meaningless Error Message no information has been provided about the error or how to fix the problem. Before you write (or rewrite) the error mes- sage, consult the developer and get a description of all the possible situations that can cause the error. If possible, group the error conditions so that a single message will suffice. Preferably, unique error conditions should generate unique error mes- sages.
194 Effective Writing Error Messages, Prompts and Warnings
User Readable Language
Including the Error Code in an error message is acceptable if the plain English rules are included. The error code is often used by users to search for solutions on the internet. However, writing error messages with obscure data and code extracts is of no help to users at all, as illustrated in Figure 9, Errors in User Readable Lan- guage.
FIGURE 9. Errors in User Readable Language
Messages intended for analysing code or fixing bugs have no meaning or value to users. Usually they are automatically removed from the code when it is released, but some developers attempt to make these error messages comprehensible to users. The result is usually an error message that is completely useless to users.
The pickle module implements a fundamental, but powerful algorithm for serializing and de-serializing a Python object structure. But users don’t care about that. This error message is obviously meant for the developers, but sometimes appears to users of PaintShop Pro, which uses the Python scripting language.
FIGURE 10. Error Messages are for Users
Don’t Blame the User
Users WANT to complete tasks and they WANT to reach their goals! Errors in software prevent them from achieving this.
Errors intimidate novice users, and although experts are more adept at blaming the important things (the System or the Manual), error messages MUST be written to ASSIST the user. The error message in Figure 11, Error Messages that Blame the
Effective Writing 195 Writing For Developers
User, the message does not give an indication on how to seek a solution. Instead it SHOUTS at the user and implies that they are to blame for the “fatal” condition.
This error message SHOUTS at the user that it’s THEIR FAULT!
FIGURE 11. Error Messages that Blame the User
Even such new age messages like that in Figure 12, Blame the User - Nicely still aportions the blame to the user, albeit in a “nice” way. It still doesn’t give you a solution or cause.
FIGURE 12. Blame the User - Nicely
State How to Fix the Problem
The error message illustrated in Figure 13, Poor Error Message is in human reada- ble language, is polite and does not blame the user, but there is no advice on how to fix the problem. Note, too, that users will be unsure of the consequences of clicking OK.
FIGURE 13. Poor Error Message
196 Effective Writing Error Messages, Prompts and Warnings
Do not be vague about possible solutions to a problem that caused an error mes- sage.
FIGURE 14. Error Message Vague Solutions
In Figure 14, Error Message Vague Solutions the solution “...... value must be less than infinity” is vague and unhelpful. Instead, there should be a specific value or range of values or even “.....value must be an integer.”
A Good Error Message
The error message illustrated in Figure 15, Good Error Message has all the traits of a good error message.
FIGURE 15. Good Error Message
It has the following essential ingredients: • A graphical severity indicator so you know whether or not to care. • A succinct, human-readable description of the issue. • An immediate, resolvable course of action. This makes the user feel empow- ered and accomplished for acting. Neglecting this makes the user concerned and irritated. • A description of future symptoms for when/if the user does not take the sug- gested course of action. This gives the user a reason to do what you’re asking.
Effective Writing 197 Writing For Developers
• When you click OK and let the failure happen as described (the mouse won’t respond) no further errors are displayed. Instead, the user is compelled to fix the issue because they know how: replace the batteries.
Error Message Writing Techniques
We have seen examples of error messages that are almost useless to the user. Writ- ing messages to users in dialogue boxes, prompts and decision boxes is also impor- tant. In most cases, if the message was written with the user in mind, there is a good chance that it will meet the criteria we have already discussed.
The writing style for error messages, prompts and decision boxes should include the following Effective Writing techniques: • Use the Active Voice • Write clearly and without ambiguity • Avoid abreviations and jargon • Use Simple English • Avoid Hostile Words
Use the Active Voice
A good message is written in the Active Voice. See Active Voice on page 72. For example, the following is an error message that sort of meets the criteria: You entered a start date later than the end date. The Start Date must be earlier than the End Date. Check the dates and re-enter.
But this is even better: The start date must be earlier than the end date.
Write clearly and without ambiguity
Reporting errors is important for commercial and internally developed software, but it becomes a problem if the user has no idea what the issue is. Messages to the user, therefore, should not be ambiguous. Use the following techniques to avoid ambiguity: • Display only the module’s screen name or wizard name in the title bar of the message. Avoid sumarising the error in the title bar. • Use the appropriate command buttons, such as OK, Cancel, Yes, No, and Retry in the following situations:
Note: Yes and No buttons must always answer a question. You cannot have one without the other.
• To stop an operation and close the message box, use the Cancel but- ton. • To close a message box, use the Close button. • To provide more information about the cause of the error, use the Details button. • To provide more information about the solution to the problem, use the Help button.
198 Effective Writing Error Message Writing Techniques
• If a user action is included in the message, use the OK button to close the message box.
This will improve software troubleshooting and provide more effective work- arounds in the interim.
Apart from the stupidity of overwriting a file in English with a file in English, this is a straight forward copy/ paste operation. Why not treat it as such?
Quick! What button would you press if you wanted to close Smart Tools? If you answered “the X button in the upper right corner,” you win.
Yes/No answers used to offer two distinct choices....
Could you honestly hold yourself back from click- ing OK?
FIGURE 16. Ambiguous Error Messages
Avoid Abbreviations and Jargon
There isn’t a great deal of room inside dialog boxes and controls to put lengthy messages. If the space prevents spelling out the word/s, abbreviate the text accord- ing to the abbreviation rules of the language in question.
For example, the following abbreviations, if necessary, are acceptable: temp = Temporary config = Configuration char = Character pt = Point
These examples should be spelt out: spec
Effective Writing 199 Writing For Developers
stats parens auth xact
Even experienced users can interpret abbreviations and jargon in subtly different ways than the message intended.
FIGURE 17. Avoid Jargon in Error Messages
Use Simple English
Use simple English to write error messages and dialogue box messages. Not only does this save space, but it makes your text more concise. See Use Simple Words on page 75 for more information.
“Valid authentication credentials were not pro- vided”. What’s wrong with “Wrong Password?”
After reading this poorly written error message, what would you have clicked?
FIGURE 18. Use Simple English
200 Effective Writing Error Message Writing Techniques
The more text there is, the harder the text is to scan, and the more likely users won't read the text at all. Use simple English to reduce the text down to its essentials and avoid the kind of error messages illustrated in Figure 19, Wordy and Irrelevant Detail.
FIGURE 19. Wordy and Irrelevant Detail
Consider the following simple English rules to help you write a good error mes- sage: • Keep sentences simple, but complete. • State the essential information at the beginning of the message. • Use the present tense to describe the conditions that caused the problem. Only- use past tense to describe an event that occurred in the past. • Avoid uppercase text and exclamation points. • Don’t leave out descriptors and articles. For example, Specify UserID when Detect set to No should be changed to Specify theUserID field when the Detect option is set to No. • Avoid using "please". It makes the user believe the action is optional.
Avoid Hostile Words
Avoid hostile words such as abort, kill, invalid and terminate. Use stop instead.
Hostile words: • Are NOT polite • Are NOT helpful • Hurt the user’s feelings
Effective Writing 201 Writing For Developers
The severity indicator icon should clearly communicate the seriousness of the error without the hostile language. Not a friendly error message! “Invalid” is a hostile word. It is NOT helpful. This error message gives you no idea of what part of the search term was “invalid”. It also doesn't tell you exactly which characters aren't allowed.
My name is valid. Maybe I simply mis-typed it. How about “Check the Spelling of your Last Name”.
This error message appears when configuring Nero Home. Nero is a little homi- cidal!
FIGURE 20. Avoid Hostile Words
Also avoid the following negative words: • Unable. This is borderline passive voice. Use cannot or could not. • Bad. Error messages like bad result have no meaning. The error message should explain why the result is “bad”, for example, “connection lost”. Use incorrect instead of bad. • Illegal. This word means “against the law.” Explain the problem that is inferred by the text that comes after “illegal”, for example, “Illegal Operation” might mean “Operation cannot proceed – file name too long.” • Unknown. If a user sees the message “error: unknown response”, the user will not know what the response is. How do you know the response is erroneous? Try “Unrecognised” and include the value that triggered the error.
202 Effective Writing Review Messages
Review Messages
Like any other document, error messages should be reviewed before they go live, or into production. Peer review of some sort is essential.
FIGURE 21. Peer Review Your Messages
Beta messages left behind due to a poor testing regime will embarrass more people than the user.
Software developers often code around error messages to find bugs and memory leaks. Make sure the soft- ware receives adequate quality analysis before release!
FIGURE 22. Error Messages that Slipped Through
Effective Writing 203 Writing For Developers
Poor grammar in error messages is usually because the Tech Writer wasn’t con- sulted on writing the text. Spelling mistakes make the software look sub-standard.
FIGURE 23. Spell Check Error Messages
204 Effective Writing CHAPTER 16 Quiz
Test your Effective Writing knowledge by completing this quiz.
Negative to Positive
Not, No, Nothing, Nowhere, Don’t, Won’t, Can’t, are negatives. Yes, Do, Will, Shall, Can, are positives. Positive writing helps readers remember what they should do because readers recall positive words in preference to negative tones. Convert the following negative sentences to positive:
Negative Positive
Not many of the animals were unfriendly
49 per cent of students failed to get an A grade. Our flight wasn’t delayed Most aren’t allergic to nuts. We had a small number of complaints about the service.
Active vs Passive
Active verbs (or the active voice) make your writing simpler, less awkward, clearer and more precise. Turn the following passive statements into active statements: The coast was ravaged by the storm.
Effective Writing 205 Quiz
The correct response to the Save prompt depends on whether you want to save the data or Cancel the action.
In the unlikely event of a fire, you should break the glass and then press the Fire Alarm button to summon the fire brigade.
Get to the Point
When writing descriptions, explanations and notes, readers will quickly and easily absorb extra information if the writer adopts an active writing style.
Avoid unnecessary introductory text to help readers immediately get the message.
Try to start the step with the verb that tells the reader what is happening. Leave the details to the body of the sentence. For example: Beginning with a clause: Using a 12mm adjustable spanner, connect the gas hose to the BBQ burners. Getting to the point: Connect the gas hose to the BBQ burners using a 12mm adjustable spanner.
Getting to the point means telling the reader what to do. Rewrite the following steps in a more straight-forward form: With the dial at 50%, rotate the outer ring until the red dot aligns with the white dot on the inner ring.
Since it may be unsafe, never switch on the gravitas rotor while the mech- anism is cycling.
Unlike the earlier model, the Kaybee 621 does not need to be lubricated sooner than its 100th operation cycle.
When lubricating the inner flush-bearing, use a nozzle made to fit the aperture.
With the speed dial on low, start the smoothing operation.
206 Effective Writing Before beginning to round the edges of the medium-size widget, adjust the turning guide to fit tightly against the bowl.
The 423-Widget needs special care, so use only as much pressure as neces- sary to push and release the tension ring.
Sentence Length
Long sentences make any document hard to read, so keep your average sentence between 8 to 15 words. Using ordered lists (bullets) to shorten sentences that describe multiple items is a good technique. Re-write the following using a more acceptable sentence structure. The three tabs at the top of the frame provide navigation functions for on line help, and are the Contents tab, which is the default view for navigat- ing the document, the Index, which is a searchable, full text index of key- words in alphabetical order, the Search tab which displays the search tool to locate keywords in the document and the Glossary tab, which displays an alphabetical list of Terms and Definitions.
Who-Does-What
The Who-Does-What order will cut out wasted words and encourage you to write your sentences with active verbs. For example: Padded and Passive: Additional information can be obtained by employees from the intranet site.
Who: employees Does: obtained What: Additional information Concise and Active: Employees can obtain additional information from our website.
Effective Writing 207 Quiz
Using this principle, re-write the following to remove word padding and make it less passive. This proposed rule was published by General Counsel in the Federal Reg- ister.
Summary data of the selected record in the results list is displayed in the Quick View panel at the bottom of the screen.
Simplifying Complex Words
Simple, everyday words will help you get your message across. Simple words such as extra, show, start and spread are far easier to understand than their complex counterparts additional, indicate, initiate and proliferate. Write the corresponding simple word to the following complex words:
Complex Word Simple Word articulate explain culmination endeavour facilitate indication reiterate subsequent utilise
Complex to Simple
Refer Write in Plain English on page 63 and Use Simple Words on page 75. Well known proverbs are trapped within the following statements, which use flowery, excessive language and big words. Release them by using simple English. An ignoramus and his lucre are readily disjointed.
In the absence of the feline race, certain small rodents will give themselves up to various pleasurable pastimes.
208 Effective Writing Impetuous celebrity engenders purposeless spoilage
Illegal transgression has no remuneration for its perpetrators.
A winged and feathered animal in the digital limb is as valuable as a duet in the shrubbery.
The warm-blooded class avers who is governed by promptitude can appre- hend the small, elongated and lender creeping animal.
Provide the privilege of emancipation, or endow me with my mortal demise.
A condition characterised by tardiness is more desirable than one that is systematically marked by eternal absenteeism.
Members of an avian species of identical plumage congregate ensemble.
Surveillance should precede saltation.
Pulchritude possesses solely cutaneous profundity.
It is fruitless to become lachrymose over precipitously departed lacteal fluid.
Freedom from encrustation of grime is contiguous to rectitude.
Effective Writing 209 Quiz
The stylus is more potent than the claymore.
It is fruitless to attempt to indoctrinate a superannuated canine with inno- vative manoeuvres.
The temperature of the aqueous content of an unremittingly ogled sauce- pan does not reach 212 degrees Fahrenheit.
All articles that coruscate with resplendence are not truly auriferous.
Where there are visible vapours having provenance in ignited carbona- ceous materials, there is conflagration.
A plethora of individuals with expertise in culinary techniques vitiate the potable concoction produced by steeping certain comestibles.
Male cadavers are incapable of yielding any testimony.
Individuals who make their abode in vitreous edifices would be advised to refrain from catapulting petrous projectiles.
Unwords
Underline the words that do not exist in a standard dictionary. You can use a dic- tionary to check if you wish. To view images on your computer screen, place the CD in the drive irregard- less of whether the drive is a CD drive or a DVD drive.
Make a bulleted list that has been indentified by the tab key.
Car drivers are totally acluistic about the distance a truck requires to stop before a collision is imminent.
The kangaroo cull is arguably the most animane way to ensure the population is sustainable.
210 Effective Writing Misplaced Modifiers
Misplaced Modifiers are single words, phrases, or clauses that do not point clearly to the word or words they modify. As a rule, related words usually should be kept together. Re-write the following examples so that the modifier is close to the word/ phrase that it modifies, thereby ensuring that the meaning is clear: The clerk handed the groceries to the customer in a paper bag.
The woman was escorted by her husband wearing a black velvet gown.
She waved at me as I left with her right hand.
Parallel Construction
Parallel construction makes a strong point and creates a smooth flow by combining two or more ideas or attributes in a single sentence. There are two rules of Parallel Construction: • Persistent Prepositions/articles. If the preposition or article (a, an, the) is the same for all items in a list, the writer can decide to include them in all of the items or write it just in the first. For example: Incorrect: Paula went to work, a restaurant, and to the movies.
The items in the list in the example above are work, a restaurant, and the movies. However, the writer used the preposition to with the first and third items only. Correct: Paula went to work, a restaurant, and the movies. Correct: Paula went to work, to a restaurant, and to the movies. • Persistent Grammatical Form. The words in the list must be of the same gram- matical form, that is, all nouns, all infinitives, or all clauses. When used incor- rectly, the sentence sounds wrong: Incorrect: I find surfing more pleasurable than to ski. Correct: I find surfing more pleasurable than skiing.
Use the correct parallel construction to make the following examples stronger and create a smooth flow:
Tom likes books, movies, and he enjoys swimming.
The spectators arrived by car, taxi, and by bus.
Effective Writing 211 Quiz
The panel found that examining the applicants' designs was more helpful than to read their references.
Wasted Words and Unnecessary Words
Many words and phrases fail to add anything to a sentence. Re-write the following phrases leaving out the unnecessary words:
TABLE 27. Wasted Words
Fat Lean Bought up Bought Sold off Owing to the fact that….. In the modern period of time…. At an earlier date…. Exact duplicate Estimated at about….
Apostrophe Abuse
The rules concerning the use of Apostrophes in written English are very simple:
They are used to denote a missing letter or letters, for example: • I can't instead of I cannot • I don't instead of I do not
They are used to denote possession, for example: • the dog's bone • the company's logo
Correct the following mis-use of apostrophes:
Incorrect Correct She hasnt been seen since. You should view this in it’s entirety. Several companies’ collapsed. Your wearing the wrong tie.
212 Effective Writing Incorrect:
Correct:
Colons
A colon is used to: • Introduce lists, for example: Correct: The old stereo had three speeds: 78, 45, and 33 1/3. Incorrect: The old stereo speeds were: 78, 45, and 33 1/3. Correct: He was fluent in two languages: Russian and Greek. Incorrect: He was able to read: Russian and Greek. • Introduce a quotation when it follows a complete sentence: Correct: My mother started every meal with the same comment: “Eat it or I’ll throw it to the hogs.” Incorrect: My mother started every meal with the same comment, “Eat it or I’ll throw it to the hogs.” • Separate a title from a subtitle Correct: She was reading Playing the Oriental Lute: Basic Lessons from Too Ning. Incorrect: The book’s title was Betting on the Dogs Through the Eyes of a Grayhound. • Separate two independent clauses when the second clause explains the first clause or gives an example: Correct: The advice my dad gave me was sound: don’t sweat the petty stuff and don’t pet the sweaty stuff. Incorrect: The advice my dad gave me about: don’t sweat the petty stuff and don’t pet the sweaty stuff was sound.
Read each of these sentences and indicate whether the colon is correctly placed. There was only one thing that Mr. Colbert worried about: exactly where was the bear at that moment. She was responsible for: invitations, seat assignment, and greeting the guests. She was able to sing: pop, opera, country, and soul. He had only one need in order to survive: water. They enjoyed challenges such as: swimming, boating, and rock climbing. Don’t ever forget rule Number One: the boss is always right. They gave him a choice of transportation: trains, planes, and automobiles, but he said he didn’t really want to travel. To Whom It May Concern: is not a good way to start a letter.
Effective Writing 213 Quiz
Everything went wrong at once: the storm hit, the window broke, Jill dropped the flashlight in the pond, and Hal let the cat slip out the door. To Whom It May Concern:
Poor English
The following sentences contain examples of poor English. Rewrite the sentences correcting the mistakes.
Points ignition systems have been obsoleted by electronic ignition systems.
Network access cannot be actioned until the form is completed, signed and dated.
I couldn’t of seen the car coming, otherwise I wouldn’t of stood in the mid- dle of the road.
The committee was comprised of club members, accountants and spon- sors.
The Knight is equally as important as the Castle.
Egg Corns
Correct the following spell as you speak errors (egg corns):
Treecats have three fingers and a poseable thumb.
Whenever someone starts comparing the President to Hitler, it is a far- gone conclusion that reason has flown out the window.
For all intensive purposes, it is just databases and an encryption key.
214 Effective Writing If you are gamefully employed, you are eligible for the $2,000 annual tax deduction.
I need some ballistic vinegar in this recipe.
Procedure Writing Exercise – Video Recorder
The video player timer is flashing and is not set to record any programs. You need to have your favourite program recorded, as you're going out, but your Mum/Part- ner/Room mate is hopeless, and can't remember how to use the program timer thingy. You are going to have to leave instructions on how to operate the recorder. You write the following instructions: Mum. Let's see if we can get it right this time. I don't want to be watching Funniest Home Videos like last time! You need to put the video in the machine and then press the record button. That's the small red one which is a little to the left of the play button, which looks like a Smartie with an arrow on it - you can't miss it. The stop button is just below the play but- ton, I think. Oh, by the way, don't forget to rewind the tape first, and you'll need to change the channel, too, probably channel 5. Pick a video that still has the little tab on the back so that it can record.
When you come home, you play back the video and you see the last half of Funni- est Home Videos and the rest is snow and white noise. Using the information above, re-write the instructions so that the reader will have a better than even chance of successfully setting up the timer.
Effective Writing 215 Quiz
216 Effective Writing Effective Writing Quiz Solutions
Effective Writing Quiz Solutions
Negative to Positive
Not, No, Nothing, Nowhere, Don’t, Won’t, Can’t, are negatives. Yes, Do, Will, Shall, Can, are positives. Positive writing helps readers remember what they should do because readers recall positive words in preference to negative tones. Convert the following negative sentences to positive:
Negative Positive Not many of the animals were unfriendly . Most of the animals were friendly. 49 per cent of students failed to get an A 51 per cent of students got an A grade. grade. Our flight wasn’t delayed. Our flight was on time. Most aren’t allergic to nuts. A small minority are allergic to nuts. We had a small number of complaints Most people were happy with the service. about the service.
Active vs Passive
Active verbs (or the active voice) make your writing simpler, less awkward, clearer and more precise. Turn the following passive statements into active statements: The coast was ravaged by the storm. The storm ravaged the coast. The correct response to the Save prompt depends on whether you want to save the data or Cancel the action. At the Save prompt, Click Save. In the unlikely event of a fire, you should break the glass and then press the Fire Alarm button to summon the fire brigade. In case of fire: 1. Break Glass 2. Press Fire Alarm button
Get to the Point
Rewrite the following steps in a more straight-forward form: With the dial at 50%, rotate the outer ring until the red dot aligns with the white dot on the inner ring. Set the dial at 50% and rotate the outer ring so the red dot lines up with the white dot on the inner ring. Since it may be unsafe, never switch on the gravitas rotor while the mech- anism is cycling. Never turn the gravitas rotor on when the mechanism is cycling. Unlike the earlier model, the Kaybee 621 does not need to be lubricated sooner than its 100th operation cycle. Don’t lubricate the Kaybee 621 until the 100th operation cycle. When lubricating the inner flush-bearing, use a nozzle made to fit the aperture. Lubricate the inner-flush bearing using a nozzle made to fit the aperture. With the speed dial on low, start the smoothing operation. Start the smoothing operation by setting the speed dial on low.
Effective Writing 217 Before beginning to round the edges of the medium-size widget, adjust the turning guide to fit tightly against the bowl. Adjust the turning guide to fit tightly against the bowl before beginning to round the edges of the medium-size widget. The 423-Widget needs special care, so use only as much pressure as neces- sary to push and release the tension ring. Press only as hard as necessary to release the tension ring of the 423-Widget.
Sentence Length
The following three tabs at the top of the frame provide navigation functions for on line help: • Contents tab. The default view for navigating the document. • Index. A searchable, full text index of keywords in alphabetical order. • Search tab. Displays the search tool to locate keywords in the document. • Glossary tab. Displays an alphabetical list of Terms and Definitions.
Who-Does-What Padded and passive: This proposed rule was published by General Coun- sel in the Federal Register.
Who: General Counsel Does: published What: proposed rule Concise and active: General Counsel (who) published (does) this pro- posed rule (what) in the Federal Register. Padded and passive: Summary data of the selected record in the results list is displayed in the Quick View panel at the bottom of the screen.
Who: The Quick View Panel Does: displays What: summary data Concise and active: The Quick View panel at the bottom of the screen dis- plays summary data of the selected record.
Simplifying Complex Words
Simple, everyday words will help you get your message across. Simple words such as extra, show, start and spread are far easier to understand than their complex counterparts additional, indicate, initiate and proliferate. Write the corresponding simple word to the following complex words:
Complex Word Simple Word articulate explain culmination end endeavour try facilitate ease or help indication sign reiterate repeat subsequent later utilise use
218 Effective Writing Effective Writing Quiz Solutions
Complex to Simple Pulchritude possesses solely cutaneous profundity Beauty is only skin deep It is fruitless to become lachrymose over precipitously departed lacteal fluid Don't cry over spilled milk Freedom from encrustation of grime is contiguous to rectitude Cleanliness is next to godliness The stylus is more potent than the claymore The pen is mightier than the sword It is fruitless to attempt to indoctrinate a superannuated canine with inno- vative manoeuvres You can't teach an old dog new tricks The temperature of the aqueous content of an unremittingly ogled sauce- pan does not reach 212 degrees Fahrenheit A watched pot does not boil All articles that coruscate with resplendence are not truly auriferous All that glitters is not gold Where there are visible vapours having provenance in ignited carbona- ceous materials, there is conflagration Where there's smoke there's fire A plethora of individuals with expertise in culinary techniques vitiate the potable concoction produced by steeping certain comestibles Too many cooks spoil the broth Male cadavers are incapable of yielding any testimony Dead men tell no tales Individuals who make their abode in vitreous edifices would be advised to refrain from catapulting petrous projectiles People in glass houses shouldn't throw stones An ignoramus and his lucre are readily disjointed. A fool and his money are soon parted. In the absence of the feline race, certain small rodents will give themselves up to various pleasurable pastimes. When the cat’s away, the mice will play. Impetuous celebrity engenders purposeless spoilage Haste makes waste Illegal transgression has no remuneration for its perpetrators Crime does not pay A winged and feathered animal in the digital limb is as valuable as a duet in the shrubbery. A bird in the hand is worth two in the bush The warm-blooded class avers who is governed by promptitude can appre- hend the small, elongated and lender creeping animal. The early bird gets the worm Provide the privilege of emancipation, or endow me with my mortal demise. Give me liberty or give me death
Effective Writing 219 A condition characterised by tardiness is more desirable than one that is systematically marked by eternal absenteeism. Better late than never Members of an avian species of identical plumage congregate ensemble Birds of a feather flock together Surveillance should precede saltation Translation: Look before you leap
Unwords
Underline the words that do not exist in a standard dictionary. You can use a dic- tionary to check if you wish. To view images on your computer screen, place the CD in the drive irregard- less of whether the drive is a CD drive or a DVD drive. Make a bulleted list that has been indentified by the tab key. Car drivers are totally acluistic about the distance a truck requires to stop before a collision is imminent. The kangaroo cull is arguably the most animane way to ensure the population is sustainable.
Misplaced Modifiers The clerk handed the groceries to the customer in a paper bag. The clerk handed the groceries, in a paper bag, to the customer. The woman was escorted by her husband wearing a black velvet gown. The woman, wearing a black velvet gown, was escorted by her husband. She waved at me as I left with her right hand. She waved at me, with her right hand, as I left.
Parallel Construction
Use the correct parallel construction to make the following examples stronger and create a smooth flow: Incorrect: Tom likes books, movies, and he enjoys swimming. Correct: Tom likes books, movies, and swimming.
Incorrect: The spectators arrived by car, taxi, and by bus. Correct: The spectators arrived by car, by taxi, and by bus.
Incorrect: The panel found that examining the applicants' designs was more helpful than to read their references. Correct: The panel found that examining the applicants' designs was more helpful than reading their references.
220 Effective Writing Effective Writing Quiz Solutions
Wasted Words and Unnecessary Words
Many words and phrases fail to add anything to a sentence. Re-write the following phrases leaving out the unnecessary words:
TABLE 28. Wasted Words
Fat Lean Bought up Bought Sold off Sold Owing to the fact that….. Since In the modern period of time…. Currently, Today, these days At an earlier date…. Previously Exact duplicate Duplicate Estimated at about…. Estimated
Apostrophe Abuse
The rules concerning the use of Apostrophes in written English are very simple:
They are used to denote a missing letter or letters, for example: • I can't instead of I cannot • I don't instead of I do not
They are used to denote possession, for example: • the dog's bone • the company's logo
Correct the following mis-use of apostrophes:
Incorrect Correct She hasnt been seen since. She hasn’t been seen since. You should view this in it’s entirety. You should view this in its entirety. Several companies’ collapsed. Several companies collapsed. Your wearing the wrong tie. You’re wearing the wrong tie.
Incorrect:
Correct: Others will be towed at owner’s expense.
Effective Writing 221 Colons
Read each of these sentences and indicate whether the colon is correctly placed. There was only one thing that Mr. Colbert worried about: exactly where was the bear at that moment. Correct She was responsible for: invitations, seat assignment, and greeting the guests. Incorrect - She was responsible for invitations, seat assignment, and greeting the guests. She was able to sing: pop, opera, country, and soul. Incorrect - She was able to sing pop, opera, country, and soul. He had only one need in order to survive: water. Correct. They enjoyed challenges such as: swimming, boating, and rock climbing. Incorrect - They enjoyed challenges such as swimming, boating, and rock climbing Don’t ever forget rule Number One: the boss is always right. Correct. They gave him a choice of transportation: trains, planes, and automobiles, but he said he didn’t really want to travel. Incorrect - They gave him a choice of transportation: trains, planes, and automobiles. However, he said he didn’t really want to travel. To Whom It May Concern: is not a good way to start a letter. Incorrect - To Whom It May Concern is not a good way to start a letter. Everything went wrong at once: the storm hit, the window broke, Jill dropped the flashlight in the pond, and Hal let the cat slip out the door. Correct To Whom It May Concern: Correct
Poor English
The following sentences contain examples of poor English. Rewrite the sentences correcting the mistakes. Points ignition systems have been obsoleted by electronic ignition systems. Points ignition systems have been made obsolete by electronic ignition sys- tems. Network access cannot be actioned until the form is completed, signed and dated. Network access cannot be initiated until the form is completed, signed and dated. I couldn’t of seen the car coming, otherwise I wouldn’t of stood in the mid- dle of the road. I couldn’t have seen the car coming, otherwise I wouldn’t have stood in the middle of the road. The committee was comprised of club members, accountants and spon- sors. The committee comprised club members, accountants and sponsors. The Knight is equally as important as the Castle. The Knight is as important as the Castle. Or The Knight is equally important as the Castle.
Egg Corns
Correct the following spell as you speak errors:
Treecats have three fingers and a poseable thumb.
Treecats have three fingers and an opposable thumb.
222 Effective Writing Effective Writing Quiz Solutions
Whenever someone starts comparing the President to Hitler, it is a far- gone conclusion that reason has flown out the window.
Whenever someone starts comparing the President to Hitler, it is a foregone conclusion that reason has flown out the window.
For all intensive purposes, it is just databases and an encryption key.
For all intents and purposes, it is just databases and an encryption key.
If you are gamefully employed, you are eligible for the $2,000 annual tax deduction.
If you are gainfully employed, you are eligible for the $2,000 annual tax deduction.
I need some ballistic vinegar in this recipe.
I need some balsamic vinegar in this recipe
Video Recorder Exercise Possible solution
To record a program that is playing on the TV, proceed as follows:
1. Before the scheduled start of the program, choose a tape that has the tab on the back spine intact. 2. Put the tape in the machine. 3. Press Rewind and wait until the rewinding has finished. 4. Change the channel to 5. 5. When the show starts, press Record. The Record button is the red one in the top left corner.
Tip: The Record light comes on.
6. Press Stop when the program has finished.
Effective Writing 223 224 Effective Writing