Technical writing/Writing clearly EE

• back to Technical Writing Level 1

Writing clearly Lesson Plan

Writing clearly quickly communicates information to the people who need it.

• Write in simple sentences.
• Use words that the readers understand.
• Explain what the reader does not know but do not waste the reader's time by explaining concepts that they already know.
• Utilize the most common method to define steps in a procedure or task.

Note: When defining the steps in a procedure, ensure that you are using the most common method to perform the task. For example, if the procedure requires defining how to save a document, each step in the procedure would be defined using menu commands, not keyboard strokes or shortcut menus. In addition, avoid the use of the phrase, "Do one of the following." This phrase distracts from content when multiple methods to perform the step are provided.

Example of Bad Technical Writing

Example: Imagine you are a user of the software program who wants to draw a graph using the computer software. First, the user must install the software program. Then, you can select some data with the mouse or keyboard. Then finally the user must click on the Draw button in the software program's on-screen toolbar. The computer will now hopefully draw the graph.

Questions

1. Why do the readers have to imagine? Either the readers use the software or they don't.
2. Why mention installing the software? The software would normally be installed by an IT department.
3. Why is the instruction of how to select data bad?
4. Would a numbered list help?
5. Why use the most common method to define a step in a procedure or task?

Exercise 1

Rewrite the bad example above using MS Excel or other similar application to draw the graph

• Only explain new terms
• Give your reader the information required to draw a graph
• A screen shot will help

Put important information first

Important information must be at the beginning of the sentence. The reader then knows what the most important part of the sentence is. This rule applies to English and may be different in other languages.

Example of unclear writing

Example (1):

“We highly recommend that person or persons walking on or near the area adjacent to the cliff edge supervise children pets and it is considered ill-advised to venture past the red flags. Due to erosion and high winds there may be a heightened risk of injury/fatality due to falling. Actions such as these may result in a dangerous fall necessitating emergency service assistance which may include the Air Force (AF) or Coast Guard Helicopter Search and Rescue Service. These services will be chargeable to the incumbent and therefore it is recommended that visitors to this area remain at a safe distance to maintain the personal safety.”

Example (2):

1. On the File menu, click Open.

2. In the Open dialog box, browse to the appropriate file location.

3. Click the file to select it.

4. Do one of the following:

Click Open.

- OR -

Press Enter on the keyboard.

Example of clear writing:

Danger! Do not cross the red flags. Stay away from the cliff edge. If you fall then we will charge you for the rescue

George Orwell's rules for writing:

Compare how similar they are to the technical writing rules

1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
2. Never use a long word where a short one will do.
3. If it is possible to cut a word out, always cut it out.
4. Never use the passive [voice] where you can use the active.
5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
6. Break any of these rules sooner than say anything outright barbarous.”

Note: there are three exceptions specific to technical writers:

1. If the reader always uses particular metaphor or simile in their work use that metaphor or simile. The first rule only applies to journalism and fiction writing.
2. If a scientific or jargon word is an Industry standard of the industry, use that word.
3. Once a word or term is defined in the document it must be used consistently as defined.

How long should a sentence be?

• Every sentence should be as short as possible.
• Every sentence must express a concept.
• Every additional word increases translation costs.
• Every additional word is a word that can be misunderstood

Using lists

Why use lists?

Lists are useful because they:

• Simplify long sentences
• Create information chunks

How long can a list be?

Readers can typically only remember between five and nine items. Therefore keep your lists short. Divide any list of instructions with more than seven steps into two groups.

Remember most people divide telephone number into groups of three or four numbers

Example 00420 555 888 777

End of lesson Test

1. How long should a sentence be?

2. Why do we group together information in lists?

3. What type of information is written a numbered list?