Writing Docs
Write for the stranger who is you in 6 months.
▶ the lesson · narrated sketch video · tap for sound
the intro
Documentation is how software survives its authors. A README answers three questions — what is this, how do I run it, how do I use it — and everything else is comments and decision records. Write for the reader with zero context: that reader is future you.
fun fact ✦
The best documentation habit costs ten minutes: write the decision down while you remember why.
the docs
the deep dive
the ideas behind the video — concepts, diagrams, a walkthrough and the traps to avoid
Code is a flawless record of what happens and a useless record of why. The reasoning — the rejected option, the weird constraint, the issue that explains the hack — lives only in your head, and your head has a changelog you cannot read. Writing it down is not bureaucracy; it is copying data out of the most volatile storage you own and into the most durable one.
code records what, docs record why
key terms
README
The front door: what this is, how to run it, how to use it. Missing README, locked project.
three headers, ten minutesADR
Architecture decision record: one short file per decision — context, choice, consequences.
ADR-007: why Postgres wondoc comment
A comment aimed at callers: parameters, return value, thrown errors. Written for people who never open the body.
/** @throws if id unknown */changelog
A dated, per-version list of what changed and for whom. Keep a Changelog is the usual convention.
## 2.1.0 - 2026-03-14how it works
- 1Write the three headers
What is this, how do I run it, how do I use it. That skeleton covers most READMEs ever needed; ten minutes now saves hours for every newcomer.
- 2Comment the why, never the what
The code already states what it does. Spend the comment on the reason, the trap, or the link to issue 412.
- 3Record decisions while fresh
One ADR per real decision: the options, the pick, the why. "We chose X over Y because Z" ages like wine; unrecorded, it ages like milk.
- 4Delete stale docs
Wrong documentation is worse than none, because it actively lies. Review docs in the same pull request as the change.
- 5Show, do not describe
Before-and-after screenshots in pull requests; a fifteen-second clip for anything that moves. One image replaces a paragraph of apologizing.
the code, explained
the code says what; the comment is where the why is allowed to live
side by side
comments that earn it
- why this beat the obvious way
- links to issues and specs
- warnings about hidden traps
comments that rot
- narrating what code already says
- commented-out zombie code
- jokes that outlive context
Stale docs are worse than no docs: a wrong README does not just fail to help, it walks people down a path that cannot work. Update docs in the same pull request as the change that invalidates them, or they will quietly never be updated again.
quick answers
Should code not just be self-explanatory?
Yes — for the what. Self-explanatory code removes the need to explain itself, and docs carry what code structurally cannot: the why, the tradeoffs, and how to run the thing on a clean machine.
How do I get a team to keep docs current?
Shrink the surface and attach it to the work: three README headers, one ADR per decision, docs reviewed in the same pull request. Short docs get updated; novels get abandoned.
What is the minimum viable README?
One paragraph of what it is, one copy-paste run command, one usage example. The real test: follow it yourself on a fresh clone and fix whatever made you hesitate.
quick hits about Writing Docs
short answers · interviews, tips, trivia & hidden gems