Technical Writing
Prose that ships — docs, RFCs, readmes, PR descriptions, commit messages — follows one standard so readers can navigate any of them the same way.
The standard
- Outcome first. The first sentence says what changed for whom and what the reader can now do. Context comes after the reader knows why they care.
- One meaning, one home. Each fact lives in exactly one place; every other mention links there. Duplicated facts rot at different speeds.
- Checkable statements. Prefer a statement the reader can verify with a command or a glance over an adjective. "Builds in ~40s" beats "fast".
- Layered structure. Summary, then detail, then edge cases — each layer readable alone, each deeper layer skippable.
- No filler. No restating the obvious, no throat-clearing, no AI tells
(
ai-slop-cleanerterritory; this skill composes with it).
Per surface
- Commit message: subject says what changed in one line ≤72 chars; body says why, and the constraint that made the change necessary.
- PR description: claim, evidence (before/after), reversibility — the
prskill owns the full template. - README: what it is, who it is for, the shortest working example, then everything else.
- RFC/design doc: problem, constraints, options considered with why the
losers lost (feeds from
architect), decision, migration.
Rules
- Write clean as you draft; a cleanup pass after drafting does not remove these patterns.
- Every claim carries its evidence or its label in the same sentence.
- Delete more than you add; the reader's time is the budget
(
principlesskill, Minimize reader load).