# Simplified Technical English

> Enforce ASD-STE100 Simplified Technical English (STE) in all technical documentation you write or edit. Use this skill whenever you draft, generate, or revise READMEs, specifications, design docs, architecture decision records (ADRs), runbooks, technical playbooks, API docs, configuration and setup guides, troubleshooting guides, release notes, inline code comments, or docstrings — any project documentation that describes technical aspects of a system. Apply it even when the user does not mention "STE", "controlled language", or "plain English". It keeps documentation short, active, and consistent so a global audience with basic English can read it correctly the first time. Do not apply it to marketing copy, casual chat replies, or narrative prose where a natural voice is wanted.

- Skill: `ebellefontaine/simplified-technical-english` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ebellefontaine/simplified-technical-english`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ebellefontaine/simplified-technical-english/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: ebellefontaine (https://skillmd.com/u/ebellefontaine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ebellefontaine/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.