Documentation Is a Feature, Not a Chore

The README That Was Written Once

You’ve met this repo. Everybody has met this repo.

There’s a README. It has an install section that mentions a Node version nobody has run since the pandemic, one environment variable out of the fourteen you actually need, and a heading called “Architecture” with nothing underneath it. The last meaningful commit to it was three years ago, by someone whose Slack handle no longer resolves.

So you do what everyone does. You read the code, ask in the channel, get half an answer, guess the rest, and eventually get the thing running. Two days gone. And you don’t update the README, because you’re already behind on the ticket you were given, which is exactly the same reason the last four people didn’t update it either.

How It Always Happens

The pattern is boringly consistent:

1. Developer builds feature
2. Developer thinks “I’ll document this later”
3. Developer moves on to the next feature
4. Later never arrives
5. Someone new joins and loses a fortnight working out what the first developer meant

Nobody in that sequence did anything wrong, exactly. That’s what makes it so persistent. Each individual decision to skip the docs was locally rational and the aggregate result is a codebase only knowable by interrogation.

That “Working It Out” Time Is Real Money

We treat the cost as zero because it never appears on a ticket. It isn’t zero.

It’s engineering hours that could have been features. It’s the same three questions being answered in Slack every week by the one person who understands the payments flow, who is now a human API with no rate limiting. It’s bugs shipped because somebody didn’t know that function assumes UTC. It’s good people quietly deciding this place is exhausting.

An hour writing something down saves multiples of that hour later, across everyone who comes after you, including future you who will have forgotten all of it by March. That compounds the same way technical debt does, only in the direction you actually want.

Done Means Documented

The fastest teams I’ve been on weren’t the ones that skipped the writing. They were the ones where it was simply part of finishing.

Feature isn’t done until the README explains how to use it. API isn’t done until the endpoints are written down. A decision about architecture isn’t done until there’s an ADR saying what you chose, what you rejected, and why, because the “why” is the bit that evaporates first and the bit everyone will want in eighteen months.

Put it in the definition of done and it happens. Leave it as a virtue people should aspire to and it never happens, because virtue loses to sprint deadlines every single time.

An hour writing something down saves multiples of that hour, across everyone who comes after you.

The Excuses, One at a Time

“The code is the documentation.” No. The code tells you what happens. It does not tell you why it happens, when you should reach for it, what the alternatives were, or which of the three similar-looking helpers is the one that’s actually safe to call. Self-documenting code is a real and good thing, and it still doesn’t explain intent.

“Documentation gets stale.” So do tests. So do types. We don’t abandon tests on the grounds that they might drift, we build habits and checks that keep them honest. Docs deserve the same treatment: put them next to the code, review them in the same PR, and let them be short enough that updating them isn’t a project.

“We’re moving too fast for docs.” You’re moving fast right now. Come back when half the team spends half its week answering questions a paragraph could have answered. That isn’t speed, it’s just borrowing against it.

Where This Falls Down

Very early on, this argument is weaker than I’d like it to be. Three people who wrote all of it together, sitting in the same room, genuinely do have working knowledge transfer, and formal docs at that stage can be effort spent describing something you’re about to delete. The trap is that the team grows, nobody notices the moment the informal thing stopped working, and by then the knowledge is spread across four heads and two of them have left.

And bad documentation really is worse than none. Wrong docs cost you twice: once for the time spent following them, once for the trust you never get back. Once a team decides the wiki lies, they stop reading the wiki, and everything you write afterwards is shouting into a room nobody enters.

So if you cannot commit to keeping something current, silence may honestly be the safer option. Write less, keep it true, and put it where people will trip over it rather than in a folder they’d have to go looking for.

Making It Stick

1. Add docs to the definition of done and treat “needs docs” as a blocker, exactly like “needs tests”
2. Keep docs in the repo, next to the code, changed in the same PR
3. Write the README’s first section as “how do I run this”, because that’s what everyone actually needs at 9am on day one
4. Record decisions as ADRs. What you picked, what you didn’t, and why
5. When someone asks you a question, answer it in the docs and send them the link
6. Delete anything you know is wrong. Immediately, without ceremony
7. If a doc is too long to keep current, it’s too long

I’ve never once heard anyone complain that there was too much documentation. The other question, I’ve heard rather a lot.

Until next time, happy coding!