31 The Good, The Bad, and The Ugly
Take a look at the following documents. Notice how simple adjustments in design and content to Document A improve our understanding of the information in Document B.
DOCUMENT A
I am writing to inform you that everything you will be doing has a purpose. Organization, clarity and coherence are essential to the success of your writing style. You need organization to help your reader understand where your writing is going, clarity to help your ready understand what it is you are trying to say, and coherence to keep your reader from straying from the topic you have presented. Without these three ingredients, combined in all your writing, including the most technical report imaginable, your writing will falter beyond belief. You will lose your audience, and your message will become lost.
DOCUMENT B
Everything you do, in technical writing, has a purpose. Any successful document has three essential components: organization, clarity and coherence. In order to master the concepts of technical writing, you need to master these three components.
Organization
It is essential to keep your paper organized to help your reader get from the beginning of your paper to the end.
Clarity
You need to use language your reader can understand and sentence structures you reader can follow, so your reader can understand your message without difficulty.
Coherence
Although you are an expert at your topic, you cannot “show off” for your reader by providing all you know. You need to stick to the topic you have introduced and present the material as quickly and efficiently as possible.
*******************
Obviously, these are abbreviated versions of technical documents. But hopefully they illustrate this concept well: by using such simple tools as headings, boldface and italics, you can make documents much more easily read and understood by your reader. The purpose of writing technical reports is to express information for your audience, not to impress them with your knowledge. Remember that statement: write to express, not to impress.
Now take a look at the next short document. It uses good design techniques, but obviously, that is not all that is needed in technical writing:
GRAMMATICAL RULES OF TECHNICAL WRITING
In order to write successfully, one must remember that a plethora of grammatical rules and regulations regulate how we use the English language, both in the case of mechanics and usage, which are very important guidelines to ensure a properly written English document.
Modifiers
Use modifiers sparingly, but use them correctly. Misplaced modifiers are killers: they will destroy the understanding of technical reports and should be avoided at all costs. Dangling modifiers present ten times the severity in loss of understanding. When you see either misplaced or dangling modifiers, eliminate them.
Phrases and Clauses
Again, technical writers must always be wary of using too many repetitive phrases. Gerund phrases are acceptable but only occasionally, perhaps two or three per page. Participial phrases can be more difficult to identify but can also be useful when using imperative voice. Noun phrases and prepositional phrases can kill good writing in an instant. Subordinate clauses, also, may be misleading for you audience, so most clauses should be coordinating, except when a dependent statement relies on active voice, of course only on Tuesdays when the sun is shining.
################################
.
Huh??? Obviously lots of writing tools are used here. But how effective is it? This is plain ugly writing. The writer takes no time to explain what he/she is referring to, and the reader is lost in the muck of confusing language. Another important statement to remember: define any words that your reader might not know.
Written communication is a two-way process: you need to keep your audience in mind at all times. Everything you write is for your audience’s benefit: how the reader understands, interprets and uses your material. If your audience is confused with language, for instance, your audience will not be able to participate in the writer-reader relationship. You provide information for your reader, and your reader participates by responding actively, doing something based on the material you’ve provided.
Sometimes, in technical writing, you will have to use language your reader may not know (a medical document written for a patient that uses medical terms, for instance). It’s important to know the medical terms, because you will be confronting those terms in other situations. So we do not simply remove all complicated language. It is better to use simple language, but when you need to provide technical terms (as stated above), define those terms.
Your next assignment will be to create a Cover Sheet to be used for every document you write in this course. The Cover Sheet relies on both design and content to make you and me familiar with the topic you have chosen to write about.