Six months ago, I wrote some documentation. I remember feeling good about it. Responsible, even. The kind of developer who documents things.

Today I opened it to set up the project on a new machine. Past me and present me are no longer on speaking terms.

If you've ever read your own README and thought "who wrote this, and why do they hate me?", this one's for you.

Exhibit A: the README

❌ "Setup is the usual steps." Which steps? Usual for whom? Past me knew. Past me has left the building.

❌ "Run npm start." The project moved to Docker four months later. The README did not get the memo. It still lists a Node version that would be politely described as historic.

❌ "Copy .env.example to .env and fill in the values." Twelve of the values are self-explanatory. One is called SYNC_MODE, it accepts three options, and only one of them doesn't quietly break the queue.

Exhibit B: the comments

❌ // TODO: explain this properly later. Later never came. Later is now. Later has questions.

❌ // Don't change this. No reason given. Is it load-bearing? Is it a workaround for a bug that was fixed years ago? The comment has the energy of a warning sign at an abandoned building.

❌ // increment i above $i++, faithfully documenting the one line that never needed it, right next to a forty-line method that documents nothing.

Exhibit C: the confident wiki page

❌ A page titled "How deployments work", last edited before two infrastructure changes. Every step is clear, detailed and wrong.

❌ "See the diagram below." There is no diagram below. There was a diagram. It lived in someone's personal drive.

The worst part isn't that the docs are missing. Wrong docs are worse than no docs, because you trust them. You follow them carefully, step by step, all the way off a cliff.

Why this keeps happening

When you write docs, you're the person who needs them least. Everything is fresh in your head, so every gap fills itself in as you read. "The usual steps" genuinely feels complete when you did them ten minutes ago.

And docs that live far away from the code (a wiki, a shared drive, a forgotten Notion page) don't get updated when the code changes, because nobody sees them during the change.

What actually helps

✅ Write for future you, who has forgotten everything. Picture yourself after six months on a different project, on a fresh laptop, slightly tired. That person is your reader. They need commands, not vibes.

✅ Show examples, not descriptions. "Configure the sync mode appropriately" helps nobody. SYNC_MODE=queue with one sentence on when you'd use the others helps everybody. A copy-pasteable command beats a paragraph every time.

✅ Keep docs near the code. The README in the repo, a short README inside a tricky module's folder, comments next to the weird line. Docs that live in the same pull request as the code get reviewed with it.

✅ Explain why, not what. The code already says what it does. The comment should say why it's like this: // Gateway rejects amounts with more than 2 decimals, so round before sending. Now future you knows whether it's still needed.

✅ Update docs in the same PR. Changed the setup? The README change belongs in that pull request. Make it a line in your PR template so it becomes a habit rather than a good intention.

✅ Test your docs. Once in a while, clone the repo fresh and follow the README exactly, no shortcuts from memory. Every place you get stuck is a bug in the docs. New team members are brilliant at this, so ask them to fix what they trip over.

✅ Write down decisions. A short note on why you chose this queue driver or that date format saves the same debate a year later. One file per decision is plenty.

A small bonus from the AI era

Good docs now have a second reader. AI coding tools read your README and instruction files to understand the project. Stale docs mislead them exactly the way they mislead people, just faster and with more confidence. Which is a pretty good reason to keep them honest.

Past me wasn't lazy. Past me just assumed present me would remember. Present me does not. Present me is writing things down now, mostly out of spite.

What's the most unhelpful line you've found in your own old documentation?