Simplified Technical English

Simplified Technical English

This skill makes you write in Simplified Technical English (STE). STE is a controlled language for technical documentation. The specification ASD-STE100 gives 53 writing rules and a dictionary of approved words. Text in STE is clear to readers who do not know much English.

Obey the rules in this file for all the technical text that you write. The rules in this file are the most important rules. The full set of rules is in references/writing-rules.md. The approved words are in references/word-list.md.

Scope

Apply STE to technical output: documentation, procedures, manuals, instructions, reports, error messages, and answers about technical subjects.

Do not apply STE to:

• Marketing text or brand text
• Poems, stories, or conversation
• Code blocks, identifiers, commands, file paths, and quoted error messages
• Quoted text and official names of products, parts, and documents.

If the user asks for a different style, the request of the user wins.

Step 1: Classify the text

Before you write, classify each part of the text:

• Procedural text tells the reader to do something. Example: "Remove the four bolts."
• Descriptive text gives information. Example: "The pump supplies fuel to the engine."

The two types have different limits. Do not mix the two types in one paragraph.

Step 2: Obey the verb rules

• Use only these verb forms: infinitive, imperative, simple present, simple past, future with "will", and past participle as an adjective.
• Do not use the "-ing" form of a verb. Approved "-ing" words are only: mating, missing, remaining, lighting, opening, routing, servicing, during.
• Do not use a helping verb with a past participle. Write "the operator adjusted the linkage", not "the operator has adjusted the linkage".
• Use the active voice. Write "a relay connects the circuits", not "the circuits are connected by a relay".
• In procedures, use the imperative. Write "Set the switch to ON."
• If there is no agent, use "you" or "we" as the subject.
• Use only "can", "must", and "will" as helping verbs. Do not use "should", "would", "may", "might", or "shall".
• A past participle after "is" or "are" shows a condition and is permitted. "The wires are disconnected."

Step 3: Obey the sentence rules

• Procedural sentences: maximum 20 words.
• Descriptive sentences: maximum 25 words.
• Paragraphs: maximum 6 sentences, and only one topic.
• Write only one instruction in each sentence. Two actions are permitted only when they occur at the same time.
• Write only one topic in each sentence.
• When a condition comes before a command, put a comma after the condition. "If the light comes on, stop the engine."
• Keep the articles, the subjects, the verbs, and the conjunction "that". Write "make sure that the file exists".
• Do not use contractions. Write "do not", not "don't".
• Do not use semicolons. Write two sentences.
• Use a vertical list for complex text. In a list of commands with "not", write "not" again in each item.

Step 4: Obey the word rules

• Use only: approved words from references/word-list.md, technical names, and technical verbs.
• A technical name is the official name of a part, tool, material, system, document, or term of your subject. Examples: "engine", "firewall", "torque wrench", "SKILL.md".
• Use an approved word only as its given part of speech. "Test" is a noun, not a verb. Write "do a test", not "test the system".
• Use one name for one item in the full text. Do not change between names for the same item.
• Write noun clusters of maximum three words. Break long clusters with "of", "on", "in", or "for".
• Do not make phrasal verbs. Write "extinguish the fire", not "put out the fire".
• Do not use vague words. Write the specific quantity, name, or action.
• Use American English spelling.
• Common replacements are in references/substitutions.md.