The following information is relevant to the technical language best practices, relevant to writing job steps:
Level
All technical writing should be at a level appropriate to the audience and should include enough clear explanations, examples and illustrations to enable users to understand and use the information. Writing documentation that makes a subject seem simple and clear, gives the reader confidence in their ability to learn. This document recognises and promotes widely accepted technical writing principles, and acknowledges the methodology and intent of:
- The European Aerospace and Defence Industries Simplified Technical English [1],
- ISO International Writing Standards [2], and
- Crystal Mark Plain English [3].
Voice
The common theme of these systems of writing is that, in procedural documentation, the writer ‘speaks in the active voice’ to the reader. In the active voice, the subject of the sentence does the action of the sentence. (In the passive voice, the subject receives the action.) Passive writing is protracted and indirect.
Do not use the “–ing” form of a verb unless it is part of a technical name.
When possible, start each sentence with a verb – inspect, clean replace, move, lift, lower, make sure, etc.
Write the verb as a command (an imperative), not as an indirect instruction. Do not use ‘please’ or requests to the reader.
Examples:
| ACCEPTABLE | NOT ACCEPTABLE |
| Inspect the gearbox; check the oil level | Do a gearbox inspection by checking the oil level. |
| Bend your knees when you lift the box. | When lifting the box, bend your knees. |
| Clean up any spilt oil and grease with a lint free rag. | Spilt oil and grease are to be cleaned up with a lint free rag. |
| Wear safety glasses when you use the grinder. | When you use the grinder, wear safety glasses. |
Conditional Sentences
It is acceptable to start a procedural step with a descriptive statement if a condition must be met before or during an action or a process. The descriptive statement must be separated from the remainder of the sentence with a comma or semicolon. Acceptable: Acceptable: Not Acceptable: Acceptable:
| ACCEPTABLE | NOT ACCEPTABLE |
| If the sensor does not operate correctly, disconnect it from the gearbox. | Disconnect the sensors from the gearbox if it does not operate correctly. |
| After the green light illuminates, open the door. (Note: Be wary of safety related conditional statements. If possible, put the most important action first). | Open the door after the green light illuminates. |
| Do not open the door if the pressure is above zero. (Note: This is not actually a conditional sentence now, but is the preferred method because the warning not to open the door (i.e. the most important action) is first. | If pressure is above zero, do not open the door. |
Numerals
When using numerals in text, follow the guidelines below:
Spell out the number if less than 10.
When you have a unit of measure, use digits with it. i.e. 4 metres.
Always spell out a number if it begins a sentence.
When two numbers are adjacent, spell out the first number. i.e. six 120-watt globes.
Decimals are written as digits. When a number begins with a decimal point, precede the decimal point with a zero. i.e. 0.52.
Lists
Lists make it easy for the readers to see the information they need as each item is separate, making it is easier to read each point. Use numbered or alphabetic lists for items that need to be in a specific order. If the items do not need to be in a specific order, use bullets. When using lists, follow the guidelines below:
Text
In text, use capitals (mixed case) for titles and proper nouns only. All else are in lower case (unless dictated by the template). Unnecessary capitals can cause confusion and misplace emphasis.
If all items are sentences, end each one with a full stop.
If all items are phrases or fragments do not use a full stop.
Structure list to start with fresh content, not repeated words.
Use parallel structure in the phrasing of the lists. i.e. If you use a verb to start some of the list items, use a verb to start all of the list items.
Punctuate the lead-in to a list with a colon. i.e. When using lists, follow the guidelines below:
Spaces
Use one space between a full stop and the next sentence.
Slashes
A slash ‘ / ’ indicates a choice between the words it separates. The slash means or. A slash should not be used unless the word or could be used in its place. Do not add a space between the slash and the letters on either side of it. i.e. Activity/Exercise.
Acronyms and Abbreviations
When using an acronym or abbreviation, spell it out on its first usage followed by the abbreviation in parenthesis. After introducing an acronym or abbreviation, you should consistently use it throughout the remainder of your document in place of the spelled-out text. Do not use apostrophes for abbreviations. E.g. KPIs (not KPI’s).