plain-language

Files (1)

• SKILL.md

SKILL.md (first lines)

# Plain Language

Clear, direct, useful. The reader gets it on one read.

## The core rule

**Write so your reader can find, understand, and use what they need on the first read.** Plain language is not dumbing down — it is removing obstacles: wordiness, passive construction, jargon, and buried logic.

Workflow: `decide who the reader is and what they must do` → `front-load the key point` → `cut every word that is not doing work` → `run the verification checklist`.

## Mechanics

1. **Front-load the point.** First sentence states the purpose, conclusion, or action. No throat-clearing.
2. **Short sentences.** Average 15–20 words; hard cap ~25. One idea per sentence.
3. **Active voice.** Subject acts: "The team shipped the fix" not "The fix was shipped by the team." Reserve passive for when the actor is truly unknown or irrelevant.
4. **Common words.** Plain terms over Latinates: "use" not "utilize", "end" not "terminate", "ask" not "request".
5. **Actionable verbs.** Name the action: "we will refund you" not "a refund will be issued".
6. **You, not we/them.** Address the reader directly where appropriate ("you must renew your license").
7. **Short paragraphs.** One topic per paragraph; 3–5 sentences max.
8. **No jargon, no abbreviations without explanation.** If a term is unavoidable, define it the first time in plain words.
9. **Headers that work.** Headings answer questions or state outcomes ("How to apply", "What happens next").

## Verify

- Every sentence ≤ 25 words (longest sentence check)
- First two sentences state the point and the action
- No passive-voice hits above ~10% of sentences (search "was/were + past participle")
- No words from the jargon list: utilize, leverage, facilitate, commence, pursuant to, aforementioned, henceforth, in the event that, with regard to
- Flesch Reading Ease ≥ 60 (aim 65–75)
- Read aloud: could the intended reader follow once?

## Do not

- Sacrifice precision for brevity where a term is legally or technically load-bearing
- Leave definitions out — plain language defines, it never assumes

## Example transformations

**Before:** "Pursuant to the provisions of the aforementioned policy, it is incumbent upon the employee to ensure that all expenditures incurred during the course of business travel are properly documented and submitted in a timely manner for reimbursement."

**After:** "Submit your travel expenses within 30 days of your trip. Keep all receipts. We process requests within two weeks."

**Before:** "The failure of the application to launch can be attributed to a misconfiguration in the environment settings, which was introduced during the most recent deployment."

**After:** "The app won't start because the latest deployment misconfigured the environment. We have rolled back the change and are redeploying now."

From surendranb/writing-skills, MIT.

More from surendranb/writing-skills