From Wikiversity

• back to Technical Writing Level 1

Contents 1 Writing clearly Lesson Plan 1.1 Example of Bad Technical Writing 1.2 Questions 1.3 Exercise 1 2 Put important information first 2.1 Example of unclear writing 2.2 Example of clear writing: 2.3 George Orwell's rules for writing: 2.4 How long should a sentence be? 2.5 Using lists 2.5.1 Why use lists? 2.5.2 How long can a list be? 3 End of lesson Test

[edit] 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 readers time by explaining concepts that they already know.

For example if the reader uses a computer regularly then do not explain how to use a mouse. Just tell the reader which button to click.

[edit] 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.

[edit] 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?

[edit] 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

[edit] 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.

[edit] Example of unclear writing

Example: “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.”

[edit] 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

[edit] 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.

[edit] 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

[edit] Using lists

[edit] Why use lists?

Lists are useful because they:

• Simplify long sentences
• Create information chunks

[edit] How long can a list be?

Readers can remember 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

[edit] 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?