Plain English
Write prose that a reader with a different first language and culture understands on the first pass. The skill covers a README, a landing page, a release note, a design document, a commit body, a tracker record and an error message. For a catalog guidance body, use the catalog-authoring skill.
Rules
Write ASD-STE100 Simplified Technical English:
- One word, one meaning. A synonym reads as a second thing.
- Active voice. "The gate refused the commit", not "the commit was refused".
- Short sentences. 20 words or fewer for an instruction, 25 or fewer for a description.
- One idea per sentence. Do not join two facts with a dash, a colon or a semicolon.
- Keep
a, an, the and that. Without them the reader reads the sentence twice.
- Three nouns together at most. "the cost of a lane", not "lane token cost floor".
- No idiom, slang or metaphor, unless this repository defines the term. Idiom does not survive translation.
- No
-ing verb where a plain verb works. "the gate refuses", not "the gate is refusing".
- Write an abbreviation in full the first time.
- Put bad news first. A correction, a limit, an overrun or a broken assumption goes above the good news.
- Mark every number as measured, sourced or assumed. Name the command for a measured number and the source for a sourced one.
Delete marketing
| Delete |
Write |
Four pillars, not a bundle of files |
Four pillars |
Read the design, not just the pitch |
Read the design |
One command, into any git repo |
Install into any git repo |
The process is code, and so is the enforcement |
The workflow and the gates are code |
What is unusual here is that … |
the fact |
The pattern is "X, not Y". Test it: name Y and ask who believed it.
- Keep it when Y is a misreading that a careful reader would make. "A lane claim is a lease, not ownership" removes an error.
- Delete it when Y is a strawman, an unnamed competitor or nothing. Then it only adds emphasis.
- In a title, delete it almost always. A title names the section.
Also delete:
- A comma that joins a second clause to a title to make it sound important. Put that clause in the body.
Plenty of projects …, What is unusual …, The only harness that …. A comparison is a claim and needs evidence. Measure it or delete it.
Structure
| Form |
Use |
| Table |
Compares two or more things |
| List |
Counts things |
| Code block |
Real output that you copied, never output that you imagined |
| Paragraph |
Explains one thing |
A paragraph that describes a shape does not show it. Draw the shape.
Before you commit the text
- Read each sentence as a person with a different first language. Replace a word that works only in your culture.
- Check each claim. Every quoted command must exist, every path must resolve, and every transcript must be one you ran.
1---2name: plain-english3description: 'Writes plain prose for readers of any language: READMEs, release notes, design docs, records. Use when writing text for a person.'4metadata:5 source: https://skillmd.com/skills/niksavis/plain-english6---78<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->910# Plain English1112Write prose that a reader with a different first language and culture understands on the first pass. The skill covers a README, a landing page, a release note, a design document, a commit body, a tracker record and an error message. For a catalog guidance body, use the `catalog-authoring` skill.1314## Rules1516Write ASD-STE100 Simplified Technical English:1718- **One word, one meaning.** A synonym reads as a second thing.19- **Active voice.** "The gate refused the commit", not "the commit was refused".20- **Short sentences.** 20 words or fewer for an instruction, 25 or fewer for a description.21- **One idea per sentence.** Do not join two facts with a dash, a colon or a semicolon.22- **Keep `a`, `an`, `the` and `that`.** Without them the reader reads the sentence twice.23- **Three nouns together at most.** "the cost of a lane", not "lane token cost floor".24- **No idiom, slang or metaphor**, unless this repository defines the term. Idiom does not survive translation.25- **No `-ing` verb where a plain verb works.** "the gate refuses", not "the gate is refusing".26- **Write an abbreviation in full the first time.**27- **Put bad news first.** A correction, a limit, an overrun or a broken assumption goes above the good news.28- **Mark every number as measured, sourced or assumed.** Name the command for a measured number and the source for a sourced one.2930## Delete marketing3132| Delete | Write |33| --- | --- |34| `Four pillars, not a bundle of files` | `Four pillars` |35| `Read the design, not just the pitch` | `Read the design` |36| `One command, into any git repo` | `Install into any git repo` |37| `The process is code, and so is the enforcement` | `The workflow and the gates are code` |38| `What is unusual here is that …` | the fact |3940The pattern is **"X, not Y"**. Test it: name Y and ask who believed it.4142- **Keep it when Y is a misreading that a careful reader would make.** "A lane claim is a lease, not ownership" removes an error.43- **Delete it when Y is a strawman, an unnamed competitor or nothing.** Then it only adds emphasis.44- **In a title, delete it almost always.** A title names the section.4546Also delete:4748- A comma that joins a second clause to a title to make it sound important. Put that clause in the body.49- `Plenty of projects …`, `What is unusual …`, `The only harness that …`. A comparison is a claim and needs evidence. Measure it or delete it.5051## Structure5253| Form | Use |54| --- | --- |55| Table | Compares two or more things |56| List | Counts things |57| Code block | Real output that you copied, never output that you imagined |58| Paragraph | Explains one thing |5960A paragraph that describes a shape does not show it. Draw the shape.6162## Before you commit the text63641. Read each sentence as a person with a different first language. Replace a word that works only in your culture.652. Check each claim. Every quoted command must exist, every path must resolve, and every transcript must be one you ran.