simple-english

# Simple English: Write Like an Aerospace Manual Write technical text with the rules of ASD-STE100 Simplified Technical English. STE is the controlled language that aerospace and defense manufacturers use for maintenance documentation. The rules exist so that a tired reader who is not a native English speaker cannot misread an instruction. They remove the usual signs of AI-generated text as a side effect: long sentences, synonym rotation, hedges, filler, and decorative clauses. Write for that tired reader. Each sentence must survive one read. ## Your Task When asked to write or rewrite technical text: 1. **Select the mode** (pragmatic or strict, below). 2. **Classify each passage** as procedural or descriptive. Every other rule depends on this. 3. **Fix your vocabulary before drafting.** Pick ONE verb for the check/verify/confirm/validate concept and ONE noun for config/settings. Use no other word for these concepts in the whole document. 4. **Apply the rules** from the catalog below. 5. **Run the self-check** before you deliver. This step is not optional. 6. **Never touch code**, identifiers, commands, or quoted errors (see Untouchables). When asked to CHECK text instead of writing it, report each violation as: rule number, the offending text, a compliant rewrite. Cite only rule numbers that exist in this file. Do not cite rule numbers from memory: the numbering is unintuitive and models invent it (tested — an agent without this file cited "Rule 3.1: short sentences"; the real Rule 3.1 is about verb forms). ## Two Modes | Mode | When | What you apply | | ----------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Pragmatic** (default) | Docs, READMEs, error messages — the user wants clear text | All structural rules. Domain words stay ("idempotent", "webhook"). | | **Strict** | The user names STE, ASD-STE100, or compliance | Structural rules + full vocabulary discipline, and tell the user that full compliance needs the official dictionary (free at asd-ste100.org). | ## Step 1: Classify the Text | | Procedural (instructions) | Descriptive (explanations) | | -------------- | ---------------------------------- | -------------------------------------------------------------------- | | Purpose | Tell the reader what to do | Explain what a thing is or does | | Verb form | Imperative: "Install the pump." | Simple present/past/future | | Sentence limit | **20 words** (Rule 5.1) | **25 words** (Rule 6.3) | | Unit rule | One instruction per sentence (5.2) | One topic per paragraph (6.5), max six sentences per paragraph (6.6) | Do not mix the two in one passage. A "Getting started" section is procedural. An "Architecture" section is descriptive. A note inside a procedure is descriptive (25-word limit, no imperative). ## THE RULE CATALOG 53 rules in 9 sections, paraphrased from ASD-STE100 Issue 9 with software examples. The official wording is in the free standard at asd-ste100.org. ### Section 1 — Words (Rules 1.1-1.14) | Rule | Instruction | | ---- | ------------------------------------------------------------------------------ | | 1.1 | Use only approved words, technical nouns, or technical verbs. | | 1.2 | Use an approved word only as its listed part of speech. | | 1.3 | Use an approved word only with its approved meaning. | | 1.4 | Use only the approved forms of verbs and adjectives. | | 1.5 | You can use domain words as technical nouns ("webhook", "commit", "endpoint"). | | 1.6 | Use an unapproved word only when it is a technical noun or part of one. | | 1.7 | Do not use technical nouns as verbs. | | 1.8 | Use the technical nouns of your project or industry. | | 1.9 | When you pick a technical noun, pick a short and clear one. | | 1.10 | No regional, slang, or jargon words as technical nouns. | | 1.11 | One item, one name. Do not call it "config" here and "settings" there. | | 1.12 | You can use domain verbs as technical verbs ("deploy", "compile", "merge"). | | 1.13 | Do not use technical verbs as nouns. | | 1.14 | Use American English spelling. | In pragmatic mode, rules 1.5, 1.8, and 1.12 do the heavy lifting: your domain vocabulary is legal. The ones agents break are 1.7, 1.11, and 1.13. **Before:** You can webhook the event, then do a deploy. **After:** Send the event to the webhook. Then deploy the service. ### Section 2 — Multi-word nouns (Rules 2.1-2.2) | Rule | Instruction | | ---- | ------------------------------------------------------------------------------------------------------------------------ | | 2.1 | Write multi-word nouns of three words or fewer. | | 2.2 | When a technical noun needs more than three words, write it in full once, then give a short form or hyphenate the units. | Break long noun chains with prepositions (of, on, in, for): **Before:** the connection pool timeout configuration value **After:** the timeout value for the connection pool ### Section 3 — Verbs (Rules 3.1-3.7) | Rule | Instruction | | ---- | ---------------------------------------------------------------------------------------------------------------- | | 3.1 | Use only the verb forms that the dictionary gives. | | 3.2 | Use only: infinitive, imperative, simple present, simple past, simple future, past participle as adjective. | | 3.3 | Use the past participle only as an adjective ("the cached response"). | | 3.4 | No auxiliary verbs for complex constructions. No present perfect, no "is to be installed". | | 3.5 | Use an "-ing" form only as a technical noun or inside one ("logging", "the mounting bracket") — never as a verb. | | 3.6 | Active voice. In descriptive text, passive is legal only when the agent is unknown. | | 3.7 | Describe an action with a verb, not a noun ("compress the file", not "perform compression of the file"). | **Approved modals: can, will, must. Banned: should, would, may, might, could.** The standard rejects "could" even for possibility: write "an explosion can occur", never "could occur". For "should": a requirement becomes "must"; a suggestion is stated as fact or deleted. This matters double for agent instructions — models read "should" as optional. **Before:** The migration has completed and the table is being rebuilt. **After:** The migration is complete. The database rebuilds the table. **Before:** The flag can be set in the config file, making restarts unnecessary. **After:** You can set the flag in the config file. Then a restart is not necessary. **Before:** The temperature must be adjusted. **After:** Adjust the temperature. ### Section 4 — Sentences (Rules 4.1-4.5) | Rule | Instruction | | ---- | ----------------------------------------------------------------------------------------------------- | | 4.1 | Write short and clear sentences. | | 4.2 | Do not omit words or use contractions to shorten sentences. Keep articles, keep "that". | | 4.3 | Use a vertical list for complex text. | | 4.4 | Use connecting words between sentences on related topics ("Then", "As a result"). | | 4.5 | Put an article (the, a, an) or a demonstrative adjective (this, these) before nouns where applicable. | Rule 4.2 is the anti-terseness rule. STE is short sentences with complete grammar, not telegraph style: **Wrong shortening:** Ensure file exists before running. **STE:** Make sure that the file exists before you run the command. ### Section 5 — Procedural writing (Rules 5.1-5.5) | Rule | Instruction | | ---- | ---------------------------------------------------------------------------------------------------- | | 5.1 | Maximum 20 words per sentence. Warnings and cautions included. | | 5.2 | One instruction per sentence, unless two actions happen at the same time. | | 5.3 | Write instructions in the imperative: "Run the migration." | | 5.4 | Put a required condition before the command, divided by a comma: "If the build fails, read the log." | | 5.5 | Notes give information, never instructions. Notes get the 25-word limit. | **Before:** You'll want to grab the API key from the dashboard before configuring the client, which you can do under Settings. **After:** Get the API key from the dashboard, under Settings. Then configure the client with this key. ### Section 6 — Descriptive writing (Rules 6.1-6.6) | Rule | Instruction | | ---- | --------------------------------------------------------------- | | 6.1 | Give information gradually: one new fact per sentence. | | 6.2 | Use key words and phrases to give the text a logical structure. | | 6.3 | Maximum 25 words per sentence. | | 6.4 | Group related information in paragraphs. | | 6.5 | One topic per paragraph. | | 6.6 | Maximum six sentences per paragraph. | No imperative in descriptive text. Descriptions explain; procedures instruct. ### Section 7 — Safety instructions (Rules 7.1-7.3) | Rule | Instruction | | ---- | ------------------------------------------------------------------------------ | | 7.1 | Use a word that shows the risk level ("WARNING" = injury, "CAUTION" = damage). | | 7.2 | Start with a clear command or condition. | | 7.3 | Then give the risk or the possible result. | Never bury the instruction after the explanation. The pattern transfers directly to destructive CLI flags, irreversible migrations, and dangerous API options. **Before:** Note that data loss may occur in some circumstances if the destructive flag happens to be enabled when running against production. **After:** CAUTION: Do not use the `--force` flag against production. The flag deletes rows that do not match the source. ### Section 8 — Punctuation and word count (Rules 8.1-8.7) | Rule | Instruction |