blagoysimandov 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
- Read the source text. Find the text type. Procedural text gives instructions. Descriptive text gives data.
- Read
references/rules.md. Obey all the rules. - Write the new text.
- Do a check with
references/checklist.md. - 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
| Do not use | Use |
|---|---|
| commence, initiate | start |
| terminate | stop, end |
| utilize | use |
| in order to | to |
| prior to | before |
| subsequent to | after |
| in the event that | if |
| is capable of | can |
| attempt | try |
| assist | help |
| approximately | about |
| sufficient | enough |
| require | need |
| indicate | show |
| ascertain | find, make sure |
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.