Should we write docs and agent instructions in ASD-STE100 (Simplified Technical English) or Markdown?
By Soumen Sarkar · October 2026
Short answer: Both, because they do different jobs. Markdown decides how a page looks; ASD-STE100 decides how its sentences are written: short, one instruction at a time, active voice, one meaning per word. Write the file in Markdown, and the procedures, rules and warnings in it in STE.
Two versions of this page
You're reading the ordinary English version: natural sentences of any length, with explanation and asides. [The Simplified Technical English version](/answers/ste100-vs-markdown-in-ste) says the same things to the STE rules: 20 words or fewer per sentence, one instruction per sentence, active voice, simple tenses and approved words. One sentence from each:
- Here: "In STE a word means one thing, and every instruction says who does what."
- In STE: "In STE, each approved word has one meaning. Each instruction tells the reader the action to do."
What is each one?
Markdown is a lightweight markup syntax from 2004. It gives you headings, lists, links and code blocks, and says nothing about language: a Markdown file can hold a crisp procedure or a ninety-word sentence full of idioms. It's what most teams write in, from READMEs to CLAUDE.md files.
ASD-STE100 is a controlled-language standard kept by the ASD Simplified Technical English Maintenance Group. It began in the European aerospace industry in the 1980s, so maintenance manuals would be understood the same way by technicians everywhere. It has two parts: writing rules for grammar and style, and a dictionary of approved words. The current version is Issue 9, released on 15 January 2025, which kept the 53 rules, rewrote the wording of 31 of them and updated 555 dictionary entries. It's free to download from asd-ste100.org.
A few of its rules:
- procedural sentences of 20 words at most, descriptive ones of 25;
- one instruction per sentence, in the imperative ("Remove the cover");
- active voice and simple tenses;
- each approved word has one meaning, and the dictionary marks the words not to use;
- no noun clusters of more than three words.
What does writing in STE give you?
- One reading, not several. Words like "check", "run", "set" and "clear" mean many things in ordinary English. In STE a word means one thing, and every instruction says who does what.
- Better understanding of complex material. A 1995 test of airplane procedure documents (Shubert, Holmback, Spyridakis and Coney) found Simplified English made the complex documents significantly easier to understand and to find information in, with no change in reading time. Non-native readers appeared to gain the most, though the groups were too uneven to prove it.
- Documents more people can use. In aviation maintenance, about four in five technicians worldwide are estimated not to be native English speakers. Short sentences and a fixed vocabulary help them most.
- More consistent translation. When the same thing is always said the same way, translation memory reuses more, and machine translation meets fewer ambiguous sentences. We found no independent figure for the saving.
- Text you can check. Long sentences, passive voice and unapproved words can all be found by a tool. A Markdown linter checks layout; it can't tell you a sentence has two meanings.
- Clearer instructions for AI agents. An agent reads every instruction in CLAUDE.md or AGENTS.md each time and follows them literally. One instruction per sentence, in the imperative, with one meaning per word, makes each rule clear and testable. Markdown's headings and lists still help the agent, and you, find the right one.
What's the current buzz about STE and AI?
Through 2026, STE has found a second life as an agent skill: a file that tells a coding agent how to write. The best known is SimpleEnglish on GitHub, with about 4,000 stars. It works in Claude Code, Cursor, Copilot, Codex and Gemini CLI, with a plain mode for chat replies and a strict mode that adds the STE dictionary for documents. Skill directories now carry several similar STE skills.
Its author's own benchmarks report STE violations in documents falling from 4.09 to 0.91 per 100 words across eight writing tasks, and visible clutter in chat replies (bold, headers, bullets, dashes) falling from 218 instances to 11. The author is open about the caveats: Claude models scored Claude's output, and a linter measures rule-following, not whether readers understand more. Reactions are mixed; some developers find it cuts padding, others say a one-line prompt does the same. Our read: the case for STE in agent instruction files is strong on the reasoning, but the evidence so far comes from the people building the skills.
What does it cost?
- Writers need to learn the rules and the dictionary; a checker helps.
- It reads stiffly, so it suits procedures and specifications, not essays or marketing.
- Simplifying has limits: a 2025 study of aviation maintenance manuals (Wang and Friginal) warns that cutting too much can remove the connecting words that help readers understand.
- You still have to define your own technical names and verbs, and keep them consistent.
So which should we use?
Use both. Write the file in Markdown. Write its procedures, rules and warnings in STE. Leave explanations and reasons in clear, ordinary English. To see the difference, read this same answer written in Simplified Technical English. For where those instructions should live, see what goes in CLAUDE.md, AGENTS.md and team memory.
The principle behind this: Let the work speak: Our work explains itself, so nobody ever has to come and ask us.
Move as one at agent speed. Nobody waits. Add Campfyrr to Claude: it briefs every agent before it touches the code, keeps assumptions and handoffs where the team can see them, and never takes your code (what it keeps).