Simple English

Simplified Technical English

ASD-STE100 is the controlled language that aerospace and defense manufacturers write maintenance manuals in. It assumes a reader who is tired, under time pressure, and reading English as a second or third language. Under that assumption a sentence that needs a second pass is a defect, so the standard removes every construction that causes one.

The same constructions are what makes generated prose read as generated: rotating synonyms, hedged claims, 40-word sentences carrying three facts, adjectives with no measurement behind them. Fix the text for the tired reader and the machine smell goes with it.

Write so each sentence survives one read.

Pick the job

Rewrite — produce compliant text. Follow the passes below in order.

Audit — report violations without changing the text. Give the rule number, the offending span, and a compliant rewrite for each. Read references/rules.md before you cite anything: the numbering is not intuitive (Rule 3.1 is about verb forms, not sentence length) and citing from memory produces confident, wrong references.

Pick the depth

Invocation argument: $ARGUMENTS

The word practical or strict in that argument settles the depth, and anything else in it is the target text or a path to it. An empty argument means the skill triggered on its own, so decide from the request using the last column.

Name the depth you picked in your first line of output, so the user can correct it with one word instead of re-reading the whole rewrite.

Pass 1 — Classify the passage

Every rule below branches on the answer, so settle it first and keep the two kinds apart within a passage.

A quickstart is procedural. An architecture overview is descriptive. A note sitting inside a procedure counts as descriptive. It carries information only, takes no imperative, and gets the 25-word budget.

Pass 2 — Freeze the vocabulary

Do this before you write a word, not during editing. One concept gets one word for the whole document, and the reader learns it once. When the word changes, the reader assumes the meaning changed too and goes looking for the difference.

Choose one from each row and use nothing else:

• check / verify / confirm / validate / ensure → one. "Make sure that" is the safest, because check and test are nouns in STE.
• config / configuration / settings / options / preferences → one.
• run / execute / invoke / launch / trigger → one.
• show / display / render / present / surface → one.
• delete / remove / drop / destroy → one word per distinct meaning, then hold them apart.
• error / issue / problem / failure → error for the message, failure for the operation that stopped.

Pass 3 — Write

Verbs

Use the infinitive, the imperative, simple present, simple past, simple future, or a past participle acting as an adjective ("the cached response"). Nothing else. Compound tenses hide time: "the migration has been running" tells the reader neither when it started nor whether it stopped.

An -ing word is legal only as a noun (logging, the mounting bracket), never as a verb and never as a trailing clause. "…, allowing you to skip the restart" is a fact hidden in a decoration. Promote it to a sentence.

Active voice. Passive is allowed only in descriptive text where nobody knows the actor.

Name an action with a verb, never with a noun made out of one. Write "encrypt the payload" instead of "apply encryption to the payload".

Approved modals: can, will, must. Rejected: should, would, may, might, could.

This one earns its keep twice over in instructions written for a model. should reads as optional and gets dropped under load.

• Before: The consumer group has been rebalanced and offsets are being committed.
• After: The consumer group rebalanced. The client commits the offsets.

Sentences

Short, but complete. Keeping the sentence under the limit is not a license to drop articles, drop that, or use contractions — telegraph style is harder to read, not easier, and it translates badly.

• Wrong shortening: Ensure bucket exists before upload.
• STE: Make sure that the bucket exists before you upload the file.

One instruction per sentence, unless two actions genuinely happen at once. Put a vertical list where a sentence would need commas to hold several items. Join related sentences with a connector — "Then", "As a result" — so the reader does not have to infer the link.

Conditions and warnings

A condition goes in front of its command, separated by a comma. A reader who meets the command first has already started acting by the time the condition arrives.

• Before: Increase visibility_timeout if the worker is slow.
• After: If the worker is slow, increase visibility_timeout.

For anything destructive, name the risk level first (WARNING for injury, CAUTION for damage or data loss), then give the command or condition, then the consequence. Consequence last, never first.

• Before: Note that running the sync with the force option enabled against production may in some cases result in data loss.
• After: CAUTION: Do not use --force against production. The flag deletes every row that the source does not contain.

Words and noun chains

One item keeps one name for the whole document. Do not verb a noun (webhook the event) or nominalize a verb (do a deploy). Keep multi-word nouns to three words, and break longer chains with a preposition.

• Before: the connection pool acquisition timeout value
• After: the timeout for acquiring a connection from the pool

American spelling. No phrasal verbs when a single verb exists: set up → install or configure, go down → decrease or stop.

Punctuation and counting

Every standard mark is allowed except the semicolon — write two sentences instead. Parentheses are fine for references, abbreviations, and short alternatives.

For the sentence limit, each of these counts as one word: a number, a number with its unit, an abbreviation, an identifier, anything in backticks or quotes, a proper noun, a title, and a hyphenated word. Text inside parentheses counts as one word in total. A colon that introduces a vertical list ends the sentence for counting.

kubectl rollout restart deployment/api costs one word, not four. Long identifiers do not blow the budget, so do not shorten a command to save room.

Delete on sight

These carry no fact. Most of the time the fix is deletion, not substitution — if you cannot say what a word adds, it adds nothing.

Two limits on this pass. Never delete a fact to fit a sentence limit — split the sentence instead. Never invent a number to replace a vague adjective. If you do not have the measurement, drop the adjective and say nothing.

Never rewrite these

Code blocks, inline code, identifiers, commands, flags, paths, environment variable names, config keys, API endpoints, product names, and quoted error or log lines. They are technical names. Reproduce them exactly, even when they break every rule in this file — a reader who copies a "corrected" command gets a new error.

Self-check before you deliver

The rewrite is where errors get introduced, so run this on your own draft.

Then count: the three longest sentences against the 20/25 limit, paragraphs against six sentences, noun chains against three words. Last, search for the words you rejected in Pass 2 and replace every hit. Every match outside code and quoted text is a violation.

Worked example

Before — a paragraph of unedited draft:

Slow queries after deploy. If you're seeing elevated latency after a deploy, it's worth checking whether the connection pool is saturated — this is often caused by long-running queries holding connections, which can prevent new requests from acquiring one. You should also verify that pool_max hasn't been left at the default (10), since this may be insufficient for production workloads, and consider enabling statement timeouts to ensure runaway queries are terminated automatically.

After — classified procedural, verb frozen to "make sure that", conditions moved to the front, one instruction per sentence:

Slow queries after a deploy. Latency increases when long queries hold every connection in the pool. New requests then wait for a free connection.

1. Make sure that the pool is not saturated. Compare the active connections against pool_max.
2. If pool_max is still 10, increase it. The default is too low for production.
3. Set a statement timeout. The database then stops a runaway query without an operator.

Sentences went from 45 words to under 20. "Checking", "verify", and "ensure" collapsed to one verb. Two conditions moved in front of their commands. pool_max and 10 are untouched and cost one word each.

Where this does not apply

STE removes persuasion by design, so it is wrong for marketing pages, launch posts, and brand writing. If the user asks for it on that kind of text, say so and offer it for the documentation the page links to.

For error messages, runbooks, postmortems, release notes, commit messages, UI copy, agent instructions, and translation prep, read references/contexts.md — the rules hold but the shape of each output differs.

Treat this file as a helper, not as a certification. ASD and the STE Maintenance Group have no connection to it, and no software can promise that a document passes. The trademark ASD-STE100 belongs to ASD, and asd-ste100.org gives the standard away at no cost.

References

• references/rules.md — the 53 numbered writing rules. Read it before citing a rule number in an audit.
• references/contexts.md — how the rules land on error messages, runbooks, incident reports, release notes, UI copy, agent instructions, and localization.