ste100-writer

ASD-STE100 Writer

What this skill does

This skill helps you to write technical documents in ASD-STE100 Simplified Technical English (STE). STE is a controlled language. It makes technical text easy to read for persons whose first language is not English. It also makes machine translation more accurate.

STE has two parts:

• A set of writing rules.
• A dictionary of approved words.

Legal limit on the dictionary

ASD owns the copyright of the ASD-STE100 specification and of the full Dictionary. This skill does not contain the full Dictionary. It contains only the writing rules and a small set of example word choices. Get the full specification at no cost from https://asd-ste100.org.

If you are not sure that a word is approved, do one of these:

• Use a word from references/word-choices.md.
• Tell the user that the word needs a check against the official Dictionary.

Do not invent a claim that a word is approved.

Procedure

1. Read the source text. Find the text type. Procedural text gives instructions. Descriptive text gives data.
2. Read references/rules.md. Obey all the rules.
3. Write the new text.
4. Do a check with references/checklist.md.
5. If the user gives you a command to show the changes, make a table with two columns: the initial text and the new text.

Core rules (short form)

Read references/rules.md for the full set.

• Write short sentences. A procedural sentence has a maximum of 20 words. A descriptive sentence has a maximum of 25 words.
• Write one instruction in one sentence. If a step has two actions, write two sentences or two steps.
• Use the imperative for instructions. Example: "Remove the bolt."
• Use the active voice. Use the passive voice only in descriptive text, and only when the active voice is not possible.
• Use the approved meaning of a word. One word has one meaning.
• Use one word for one thing. Do not use synonyms.
• Use articles ("a", "an", "the") where possible.
• Do not use a gerund (an "-ing" word) as a noun or as an adjective. A technical name is an exception.
• Use a maximum of three nouns together in a noun cluster.
• Write a maximum of six sentences in a paragraph of descriptive text.
• Put the warning or the caution before the step that it applies to.
• Start a warning or a caution with a command or with a clear condition.
• Do not use a slash ("/"), but "and/or" is permitted.
• Use simple verb tenses: the present tense, the past tense, and the future tense.
• Do not remove words to make the text short. Keep the text clear.
• Do not use em dashes

Warnings and cautions

Write a warning for a risk of injury or death. Write a caution for a risk of damage to equipment. Write the condition first, then the command.

Example of a warning:

WARNING: THE FUEL IS FLAMMABLE. KEEP FLAMES AND SPARKS AWAY FROM THE WORK AREA. FUEL FIRES CAN CAUSE INJURY OR DEATH.

Common changes

Read references/word-choices.md for more examples.

Quality check

Before you give the text to the user, do these checks:

• Count the words in each sentence.
• Find each passive verb. Change it to the active voice, if possible.
• Find each "-ing" word. Change it, if the rules do not permit it.
• Find each word from the "Do not use" table.
• Make sure that each term is the same in all of the text.
• Make sure that the technical data did not change.

Never change the technical content to obey a rule. If a rule and the technical accuracy have a conflict, tell the user.