Writing simplified technical English
ASD-STE100 is a controlled-language standard. The aerospace and defense industry wrote it so that a technician cannot misread a maintenance instruction. It removes the two biggest sources of misreading: words that carry more than one meaning, and sentences that support more than one structure.
The same discipline fixes the usual failure of agent-written prose. Agent output is often correct and unreadable: long sentences, stacked hedges, passive voice, and a synonym rotation that makes one action look like three. The reader has no author to ask, so ambiguity costs them a re-read at best and a wrong action at worst.
Apply the rules below as you write. Do not write a dense draft and clean it up afterward.
When to use this
Use it for text that a person or another agent must act on:
- Reports, findings, and summaries.
- PR descriptions, commit messages, and code comments.
- Instructions passed to another agent, and prompts.
- Tool descriptions, error messages, empty states, and log lines.
Do not use it where voice is the point: marketing copy, blog posts, or anything persuasive. STE is deliberately flat. Also leave quoted text alone. If you quote a user, a log, or a document, quote it as it is.
The rules
PostHog house style sits on top of these rules and wins where the two disagree. We use American English, sentence case, and the Oxford comma. We do not use the em-dash.
How to rewrite
- Read the text once for meaning. Do not start rewriting before you know what it must still say.
- Go sentence by sentence. Name the rule each sentence breaks.
- Rewrite the sentence to fix that break. Keep every fact, number, condition, and qualifier.
- Check the result against the rules again. A rewrite often introduces a new long sentence.
Precision beats brevity. If a shorter sentence would drop a safety condition, a scope qualifier, or a number, keep the longer sentence and say why.
If the text already follows the rules, say so. Do not change compliant text.
Self-check
Before you send the text, read it once and ask:
- Does any sentence run past 25 words?
- Does any sentence carry two instructions?
- Does the same action appear under two different verbs?
- Can a passive sentence name its actor?
- Would a reader who joins here, with no context, know what to do next?
References
references/writing-rules.md: the detail behind the table, plus sources.references/before-after.md: worked examples of the rewrite, including agent output.
