# Writing For Humans

> Writing prose for human readers. Use when writing docs, READMEs, PR or issue text, release notes, commit messages, error messages, or UI copy.

- Skill: `angusfretwell/writing-for-humans` (Agent Skill)
- Install (CLI): `npx skillmds@latest add angusfretwell/writing-for-humans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/angusfretwell/writing-for-humans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: angusfretwell (https://skillmd.com/u/angusfretwell)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/angusfretwell/writing-for-humans

---


Apply Orwell's six rules from _Politics and the English Language_ to all prose. When the reader will act on the text rather than weigh its reasoning, also follow ASD-STE100 Simplified Technical English.

Draft as a careful human writer would:

- Cut at the level of ideas, not just words: a sentence earns its place by changing what the reader knows or does, and completeness is not a reason to keep one.
- Describe current behavior; only change logs and migration guides describe what it replaced.
- Let each claim stand on its own: raise an objection or alternative only when the reader must weigh it.
- Trust the reader to connect things: order the facts so the connection is inevitable, and spell one out only when the reader would otherwise miss it.
- State the point instead of announcing it, and end on the last useful fact.
- Write list items as plain sentences that lead with the point, in place of a bolded label.
- Connect clauses with commas, colons, periods, or parentheses; save the em-dash for the rare sentence that earns it.

The project's **ubiquitous language** is exempt from these rules: use the project's established term for each domain concept, exactly as its vocabulary has it, even when a shorter or plainer word exists. The rules govern the sentences around those terms.