Documentation for future-you
The only reader who matters and what changed when the documentation got a second reader who never skims.
14 months away from a project, and back on it in May for two weeks of changes.
There’s a NOTES.md in the root that I wrote. Two entries in it did their job perfectly: one told me the deploy needs a flag I’d never have guessed and would have had to reverse-engineer from a CI config, another told me that a bit of ordering in the checkout looks wrong and is deliberate with a sentence about why which stopped me tidying it up and breaking something.
A third told me confidently how the staging environment works. That had been true in 2024 but nobody had touched the file since, including me, and I spent a couple hours finding out it was wrong, most of which I spent assuming I’d misunderstood it rather than that it was lying.
All things considered, that file was useful. But the 2 hours is the interesting part because it’s the cost that nobody accounts for when they talk about writing things down.
Know your audience
The useful move is being specific about the reader.
Future-you, at some distance, is not a beginner and not a stranger. They have every bit of general skill you have now and then some. They know the language, they know the framework, they can read the code faster than they can read your prose about the code.
What they have lost is context. Not “how does dependency injection in Magento work,” which they can look up in a few minutes, but rather: why is it done this way here, what was tried before, and what is going to look like a mistake at first glance.
Once that’s the reader, most of what people put in documentation turns out to be for somebody else, and mostly for a person who doesn’t exist.
Three categories, and only one of them pays
Things recoverable from the code, what the function does, what the components are, where the routes live. Don’t write any of these down. They’re the easiest thing in the world to obtain, and the moment you write them somewhere else you’ve created a second copy that becomes stale over time and that staleness is invisible. That’s an argument I made about commit messages in the past from the other direction: a commit message is bound to its modifications and cannot lie, whereas a paragraph in a wiki has nothing holding it to anything.
Things recoverable but expensively, the deploy sequence, the flag, the one-off command with seven arguments, which of the four env vars actually has to be set. These are worth writing down and they’re what most people mean by documentation. The return is real but confined, because the alternative is half an hour of archaeology instead of a day.
Things not recoverable at all, why the ordering matters, what we tried that didn’t work, what the client insisted on over your objection, which feature looks wrong but is deliberate, why the obvious better approach isn’t actually better here.
That third category is the whole game, and it’s the one we often neglect to write because at the time the information feels too obvious to be worth recording. It never survives. Six months is enough to lose it, and after two years it isn’t anywhere in the world except maybe in one person’s head, and eventually not there either.
The two formats I actually keep
Nothing elaborate, and I’ve tried elaborate.
A comment next to the strange line saying it’s strange on purpose. This is the highest return per second of any comments I leave. It’s in the one place guaranteed to be read by whoever is about to break it, more than can be said for a wiki, and it moves with the code when the code moves.
// Clear the session BEFORE the redirect, not after. Payment provider reenters this handler on the way back and the later version double fires the order confirmation email.
clearCart(session);
redirect(returnUrl);And a decision log: a dated list, appended to, never reorganized. Three lines an entry: what we decided, what we rejected, why. It takes about 90 seconds at the moment of deciding, the only moment you have the information.
The one that has earned its place most unexpectedly is the rejected half. Knowing that somebody already tried the obvious thing in 2024 and it didn’t work has saved me from re-running the same failed experiment at least three times, and on one of those I’d have lost the better part of a week.
The rot problem, which is the real discipline
Back to the 2 hours.
A document that’s wrong is worse than no document, because it’s confidently wrong and it comes with your own name on it so the reader trusts it and troubleshoots themselves instead of it. No document at all makes them go and look, slower and correct.
Which means the discipline is not writing more. It’s writing less and deleting aggressively.
The test I use: whenever I come back to a project after a gap, I do one small task and pay attention to what I have to work out. Whatever I spend more than a minute rediscovering goes in the file. Whatever I find in the file that’s no longer true comes out, right then, while I have the evidence in front of me.
It’s about 15 minutes and it happens at the exact moment I’m most motivated.
And now something else reads it
The part I didn’t expect, and the reason I’m writing this now rather than back in the day when I wrote about READMEs.
These files have a second reader now. Whatever your agent reads at the start of a session is documentation, written by you, for a reader with perfect attendance and no memory whatsoever, which is a rather precise description of the future-you I’ve been talking about the whole way through.
And it turned out the two are the same document. What makes a file useful to an agent is exactly what makes it useful to somebody returning after a year: specific, current, stated as a rule with a consequence, no aspiration, no “we value clean code.”
The part I found genuinely surprising is which direction the improvement ran. I started writing these files for the machine, and my documentation for people got better because the machine is unforgiving about vagueness in a way a coworker is far too polite to be. If a line is ambiguous, it does the wrong thing immediately and visibly, and then you go and fix the line. Nobody has ever given me that feedback loop on my comments before.
Which is a whole post of its own and I’ll write it properly but for now: the file you’d write for the version of yourself who forgot is the same file, and you were probably going to have to write it anyway.
Even odds
The staging note is fixed. It’s 4 lines now instead of 11, it has a date on it, and 2 of the 11 were describing something that no longer exists and are simply gone.
14 months from now I’ll be back on this and I’ll find out whether I did that well. I’d put it at about even odds, honestly, which is the correct amount of confidence to have in a person who has demonstrably done this wrong before.