Write Docs for the Version of You Who Forgot Everything

The person who'll read your documentation most is you, a few months from now, at a bad moment. The server is down, or a renewal broke, or you need to change one setting and can't remember where it lives. That person has no context and very little patience. Write for them.

Most documentation fails because it's written for the wrong reader. It explains how the code is organized, which you can figure out by reading the code. What it leaves out is everything you can't figure out from the code: why you made a weird choice, which server it runs on, where the credentials are kept, what to do when it breaks.

So my first rule is to write down the non-obvious stuff and skip the obvious stuff. "This function returns the user" is noise. "We store dates in UTC and convert in the template because the old server's time zone was wrong" is gold.

Second rule: keep it next to the thing it describes. A README in the project folder gets read. A page in some wiki you set up once and never opened again does not. If the docs live in the repo, they show up when you need them and they get updated in the same commit as the change.

Third, start with how to run it. The top of a README should answer: what is this, how do I get it running locally, how do I deploy it. Copy-pasteable commands, not descriptions of commands. If setup takes six steps, list six steps.

Fourth, keep a short operations section for the 2 a.m. version of you. Where it's hosted. Where the logs are. How to restart it. How backups work and how to restore one. Which external services it depends on. Note where secrets are stored (a password manager entry, an environment file on the server), but never paste the secrets themselves into the docs.

Fifth, write down decisions. A simple dated list of "we chose X over Y because Z" saves you from re-arguing the same thing later, or worse, undoing something that was there for a good reason.

And keep it short. Long docs don't get read, and they rot faster because nobody wants to update them. A one-page README you trust beats a forty-page manual you don't.

The best time to write it is right after you've solved something annoying, while it's still fresh. Ten minutes then saves an hour later. Every time.