Simplified Technical English for Docs
Write or rewrite technical documentation with the ASD-STE100 Simplified Technical English discipline — the aerospace maintenance-manual standard adapted for READMEs, runbooks, error messages, incident reports, and agent instructions.
The rules aerospace manufacturers use so a tired mechanic can't misread a maintenance step turn out to strip out almost every tell of unedited AI-generated prose — the long sentences, the synonym rotation, the hedging — as a direct side effect, not a coincidence.
Who it's for: technical writers standardizing documentation clarity, developers writing READMEs, runbooks, or incident reports, teams writing system prompts and agent instructions that need to survive a single read, anyone whose docs need to translate well for non-native readers
Example
"Clean up this troubleshooting section" → Passages classified as procedural or descriptive, sentences split under the 20/25-word limit, conditions moved before their commands, banned modals like 'should' and 'could' replaced with 'must' or 'can', vocabulary collapsed to one word per concept, and code/identifiers left untouched throughout
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add simplified-technical-english# Simplified Technical English for Docs
Write or rewrite technical text using the discipline of ASD-STE100 Simplified Technical English — the controlled-language standard aerospace and defense manufacturers use for maintenance documentation — adapted for software docs, runbooks, error messages, release notes, and incident reports. The rules exist so a tired, possibly non-native reader can't misread an instruction. As a side effect, they strip out most of the telltale signs of unedited AI-generated prose: long sentences, synonym rotation, hedging, and filler.
Write for that tired reader. Every sentence has to survive a single read.
## Two Modes
- **Pragmatic (default)** — for docs, READMEs, and error messages where the goal is just clarity. Apply the structural rules below; keep real domain words ("idempotent," "webhook," "endpoint").
- **Strict** — when someone explicitly asks for STE or standards compliance. Apply the structural rules plus full vocabulary discipline, and note that true compliance requires the official ASD dictionary (free at asd-ste100.org).
## Step 1: Classify Every PassageGet new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
Applies ASD-STE100 Simplified Technical English — the controlled-language standard aerospace and defense manufacturers use for maintenance documentation — to software docs, runbooks, error messages, release notes, incident reports, and agent instructions. Every passage first gets classified as procedural (tells the reader what to do, 20-word sentence cap, imperative mood) or descriptive (explains what something is, 25-word cap, no imperative), then the structural rules apply: one instruction per sentence, condition before command, banned soft modals (should/would/may/might/could all collapse to must/can or get deleted), and one consistent word per concept throughout the document.
Because the rules exist to protect a tired, possibly non-native reader from misreading an instruction, they double as an effective de-slopping pass — a companion table maps the specific words AI-generated docs overuse (leverage, seamlessly, robust, facilitate, gracefully handles) to plain replacements or outright deletion, while code, identifiers, CLI flags, and quoted error text stay untouched as the technical names they are.
Quick Start
Step 1: Create a Project Folder
mkdir simple-english && cd simple-english
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ./
Step 3: Rewrite a Passage
claude
Paste in the documentation, error message, or runbook you want rewritten and ask Claude to apply the Simplified Technical English rules. For a compliance check instead of a rewrite, ask it to report each violation by rule with a compliant rewrite.
Tips & Best Practices
- Run the self-check before delivering, every time: count your three longest sentences, search for contractions and any surviving "should," and confirm every "if"/"when" opens its sentence before the command it gates.
- The "should" ban matters more for agent-facing instructions (system prompts, CLAUDE.md) than almost anywhere else — a model reads "should" as optional even when a human author meant it as a hard requirement.
- Don't apply this to marketing copy or brand voice — it strips persuasion by design. If asked for STE on marketing text, say so and offer it for the surrounding docs instead.
Limitations
- An independent, unofficial application of a public standard's structural rules — not an official ASD/STEMG tool, and no automated pass can guarantee full compliance with the actual ASD-STE100 dictionary.
- Full vocabulary compliance (the ~900 approved words) requires the official ASD dictionary, a free download at asd-ste100.org — this playbook covers the structural rules, which get most of the clarity benefit without it.
- Best suited to technical, instructional, and safety-relevant text — applying it to narrative or persuasive writing actively works against the writer's goals.