Simplified Technical English

Simplified Technical English (ASD-STE100)

What this is and why it matters

ASD-STE100 Simplified Technical English (STE) is a controlled language for technical documentation. It exists because technical readers are often non-native English speakers, are under time pressure, or are acting on safety-critical steps. Ambiguous or complex writing causes misreading, and misreading a procedure has real cost.

STE reduces that risk by limiting vocabulary and grammar to a small, consistent set. You write plainly, one idea at a time, so the reader does not have to decode the sentence before doing the work.

STE is owned and trademarked by ASD (Brussels). The full standard (Issue 9, January 2025) has 53 writing rules and a dictionary of about 900 approved words. The dictionary is proprietary and is not reproduced here. This skill applies the public writing rules and general word-choice principles. When a project must formally certify against STE, use the official standard from https://www.asd-ste100.org/ as the authority.

When to apply it

Apply STE to the technical content you produce, including:

• READMEs and getting-started guides
• Specifications and requirements
• Architecture decision records (ADRs) and design docs
• Runbooks, operational playbooks, and troubleshooting guides
• API documentation, configuration guides, and setup instructions
• Release notes and changelogs
• Inline code comments and docstrings

Do not force STE on marketing copy, blog posts, casual messages, or places where a natural narrative voice is the goal. STE is for instruction and description, not persuasion.

STE has two content types, and some rules differ between them:

• Procedures — steps the reader does (install, configure, run, deploy).
• Descriptions — explanations of how something is or works (concepts, architecture, rationale).

Core rules to apply

Apply these while you write, not only as a review pass. Most are objective, so you can self-check them.

Sentences

• Keep procedure sentences to 20 words or fewer.
• Keep description sentences to 25 words or fewer.
• Write one instruction per sentence in procedures. Split "do X and then do Y" into two sentences or two steps.
• Keep the full sentence structure. Do not drop the subject, the verb, or articles (a, an, the) to save space.

Voice and verbs

• Use the active voice. Name the actor: "Run the migration", not "The migration should be run".
• Passive voice is acceptable only in descriptions when the actor is unknown or irrelevant.
• Use simple verb forms only: infinitive, imperative, simple present, simple past, simple future, and the past participle used as an adjective.
• Avoid the -ing form (gerunds and progressive tenses) unless it is part of an established technical name (for example, "load balancing"). Write "Use the cache" instead of "You will be using the cache".

Words

• Use one word for one meaning, and use each word as one part of speech. Pick a term and keep it. Do not call the same thing a "flag" in one place and a "switch" in another.
• Prefer short, common words over long or abstract ones. See references/word-choice.md for common substitutions.
• Keep noun clusters to three words or fewer. Break up long strings of stacked nouns; add prepositions or hyphens so the relationship is clear.
• Use approved technical names and technical verbs freely (for example, kubectl, commit, deploy, serialize). Domain terms are exempt from the general vocabulary limits — STE restricts general English, not your technical terms.

Structure

• Keep paragraphs to six sentences or fewer, with one topic per paragraph.
• Use vertical lists for sequences of steps and for sets of conditions. A list is easier to scan than a long sentence with several clauses.
• Start a safety or destructive-action note as a clear command or condition, and put it before the step it protects: "Before you delete the volume, confirm the snapshot exists."

Applying it to code comments and docstrings

Comments are technical documentation. The same rules apply, scaled down:

• Say why, not what the code already shows. STE clarity means removing noise.
• Use imperative or simple present: "Return the cached token." not "This function will be returning the cached token."
• Keep it to one idea. If a comment needs three clauses, the code may need to be split.

Examples

Example 1 — Procedure (sentence length + one instruction): Input: "After you have cloned the repository and installed the dependencies, you should then run the setup script which will configure your environment." Output:

1. Clone the repository.
2. Install the dependencies.
3. Run the setup script. The script configures your environment.

Example 2 — Active voice + simple verb: Input: "The configuration file must be updated before the service is restarted." Output: "Update the configuration file. Then restart the service."

Example 3 — Word consistency + noun cluster: Input: "Modify the user account access permission control settings toggle." Output: "Change the user permission settings."

Example 4 — Docstring: Input: # This method is responsible for handling the parsing of the incoming request payload and returning it Output: # Parse the request payload and return it.

Self-check before you finish

Read references/writing-rules.md for the full categorized rule set when you need detail. Before you deliver technical documentation, confirm:

• Procedure sentences are 20 words or fewer; description sentences 25 or fewer.
• Each procedure sentence has one instruction.
• Sentences are active, with a named actor where there is one.
• Verbs are simple tenses; no stray -ing forms.
• The same thing has the same name everywhere.
• Noun clusters are three words or fewer.
• Paragraphs cover one topic and are six sentences or fewer.
• Steps and conditions use vertical lists.
• Safety and destructive-action notes come before the step, as a command.