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

README: run itcomment: whyADR: chose Xchangelog
different homes for different jobs — mixing them up is how docs rot

key terms

README

The front door: what this is, how to run it, how to use it. Missing README, locked project.

three headers, ten minutes

ADR

Architecture decision record: one short file per decision — context, choice, consequences.

ADR-007: why Postgres won

doc 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-14

how it works

  1. 1
    Write 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.

  2. 2
    Comment 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.

  3. 3
    Record 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.

  4. 4
    Delete stale docs

    Wrong documentation is worse than none, because it actively lies. Review docs in the same pull request as the change.

  5. 5
    Show, 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

1// BAD: increments i
restates the code: zero value
2i = i + 1
3
4// GOOD: retry with backoff because
5// the rate limiter counts retries
6// as hits, so wait 2^n s (#412)
7await wait(2 ** attempt)
the why, invisible in code alone

side by side

comments that earn it

  • why this beat the obvious way
  • links to issues and specs
  • warnings about hidden traps
VS

comments that rot

  • narrating what code already says
  • commented-out zombie code
  • jokes that outlive context
🪤 gotcha

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

📚 tutorial

README vs comments vs ADRswatch ↗

🔧 useful

The three-header READMEwatch ↗

💎 deep

The stranger is youwatch ↗

💎 deep

Show, don’t describewatch ↗