There's a specific kind of regret that comes from opening a repo you built three months ago and finding a single-line README that says "coming soon." The code is all there. The logic is real. You just have no idea what anything is for, because you never wrote it down when you still knew.
I used to think documentation was the thing you wrote after the work was finished. Now I treat it as the first output — before the feature is built, before the commit goes up, before I close the laptop. This shift didn't come from some productivity philosophy. It came from getting burned, three times, in three different ways.
1.The README I had to ask for
I'd spent a full session building a new internal system — a complete operating layer for how the agency works: project state, strategy, client notes, all of it accessible to every session. The result was genuinely useful. It worked. I was pleased with it.
I looked at the repo the next day and there was no README.
I had to ask Claude to go back and write one. It did — and a good one — but the problem wasn't the quality. It was that "go write the docs" is a command that only exists because someone forgot, and now there's a whole session of context to excavate after the fact. The decisions we'd made, the structure we'd chosen, the rationale for how things fitted together — all of that was still in the transcript, but it wasn't in the place the next reader would look.
2.The version that nobody could find
Every app I ship has a product specification, a changelog, a marketplace listing. After a few months of editing across all of them, I realised I genuinely couldn't tell which version of any document was current. There were HTML exports that didn't match the Markdown source. There were spec files that described features that had since been redesigned. There were changelog entries that referenced a version number that didn't match the package.json.
The problem wasn't that I was disorganised. The problem was that docs without version numbers are implicitly permanent — they look authoritative whether they're three months stale or updated this morning, and there's no signal to tell you which.
The fix was simple: every significant document carries a version number and a last-updated date at the top, bumped on every content change. Minor edit — minor bump. Meaningful rewrite or approval milestone — major bump. And whenever the Markdown changes, the HTML export changes in the same commit, not a week later when someone notices the mismatch.
3.The commit that explained nothing
Git history only helps you if the commits say something. For a while mine didn't. Bare commits, or commits with messages like "fix" or "update" — technically correct, practically useless when you're trying to understand what changed on a given afternoon three months ago.
What I eventually wanted was a git log I could actually read: each commit as a one-line summary of intent, not just a timestamp. Not "fix: dashboard" but "fix: dashboard crashes when site has no published pages." Not "update docs" but "docs: bump PRODUCT-SPEC to v1.4, add rate-limit section."
This turned out to be one of the easiest habits to install. You're writing the message anyway. The only cost of writing a useful one is ten extra seconds of thought. The return is a history that documents itself.
feat:, fix:, docs:, refactor: — so the log stays scannable.The pattern underneath
Three different failure modes, same root: I treated documentation as the thing that happened after the real work, which meant it either happened late, happened badly, or didn't happen at all.
The reframe that actually stuck was this: documentation is the spec before you build and the receipt after you build. It does two different jobs, and neither of them is optional.
Before you build, writing the README forces you to articulate what you're making and why. Vague plans produce clear READMEs only if you're willing to resolve the vagueness first. That friction is the point — it catches confused thinking before it becomes confused code.
After you build, the docs are what make the work portable. The code belongs to whoever has the repo. The knowledge — why this structure, what that module does, what version the client approved — only travels if someone wrote it down.
The AI makes this easier than it's ever been. Claude can draft a solid README from a working codebase in a couple of minutes, version-bump a changelog entry from a diff, and write a commit message that actually reflects the change. The bottleneck was never the effort. It was the habit.
Now I ask for it at the start, not at the end. The docs come first. The code fills them in.