| name | plain-technical-language |
|---|---|
| description | Draft or rewrite technical documentation in plain language, following ISO 24495-1's four principles (relevant, findable, understandable, usable). Use when the user says "plain technical language", "/plain-technical-language", "plain English", "plain language", "ISO 24495", "make this plainer", "rewrite this plainly", "tighten this doc", or asks for a README, ADR, runbook, Confluence page, ticket, or PR description to be made clearer without dumbing it down. |
Write for a competent reader in a hurry. ISO 24495-1's four principles, applied to technical docs:
| Principle | Test |
|---|---|
| Relevant | Everything here is something this reader needs. Nothing is here to look thorough. |
| Findable | Headings, order and structure let them jump straight to their bit. Order follows what the reader needs first, not the order the work happened in. |
| Understandable | They get it on the first read. |
| Usable | They can act on it — do the thing, make the decision, find the next step. |
- Lead with the point. Conclusion first, support after. No wind-up.
- One idea per sentence, one topic per paragraph. Aim under 25 words a sentence.
- Active voice with a real subject: "the service retries" not "retries are performed".
- Verbs, not nominalisations: "we decided" not "a decision was taken".
- Keep the domain terms — plain language is not simple language. Define each one once at first use, then use it consistently. Never swap in a synonym for variety.
- Cut hedges (broadly, essentially, it should be noted), intensifiers (very, critical, robust, seamless) and filler openers (in order to, it is important that). Cut negative parallelisms from prose too — "not X, but Y", "rather than only Y" — keeping the affirmative half. Contrasts that show the wrong form, as in the rules above, are doing work; leave those.
- Concrete over abstract: name the service, the file, the number, the date. Replace "recently", "several", "significant" with the fact.
- Second person and the imperative for instructions. Numbered steps for anything sequential, one action per step.
- Headings that predict what's under them: "Rotating the signing key", not "Overview". A category word is fine when the category is the content — Testing, Prerequisites, Rollback — and wrong when it could head anything — Overview, Background, Details, Notes, Considerations.
- Tables and lists for parallel facts; prose for reasoning. Don't bullet an argument.
- Say what it means for the reader, not what the system contains.
- Don't narrate the change. Cut what the reader can get from the artefact itself — the diff, the console output, the code — and keep what it can't: why, what you tried, what you rejected, what you deliberately left alone.
- Every section earns its place. No section that restates its heading, no recap of what the reader just read. Merge two sections only where the prose repeats — a shared theme is not duplication, and merging on one moves text without cutting any.
- Don't dumb the content down. Same technical precision, fewer words in the way.
- Don't cut to reach a length. A doc whose every paragraph carries something the underlying artefact can't supply is already the right length, however long that is.
- Don't add scaffolding nobody asked for — purpose sections, glossaries, closing summaries.
- Don't describe the document's own qualities ("this comprehensive guide", "a robust approach").
- Don't go chatty. Plain is direct, not casual.
- Read it once. Work out who reads this and what they came for.
- Fix structure first — order, headings, what to delete. Most of the gain is here, not in the sentences. A restructure also reassigns emphasis: check what a heading you demoted to a bold lead-in has stopped signalling.
- Then tighten sentences against the rules above.
- Keep every technical fact, number, name and caveat. If something looks wrong or missing, flag it rather than smoothing it away. Check the lead claims and counts still match the body — "three fixes", "two cases" — since that is what goes quietly wrong.
- Show the rewrite. Where a cut loses something arguable, name the line and why.
- UK English in prose, US English in code identifiers — see
org-conventions. - Pairs with
humanize: that one strips AI tells from any writing, this one is the plain-language standard for technical docs. Load both when a doc is bloated and AI-flavoured. - ISO 24495-1:2023 supplies the four principles; the rules are the house application of them.