Documentation has a bad reputation: either sprawling enterprise wikis no one reads or nothing at all.
For a solo operator, you don’t need a thousand pages. You need a map you can still read when you’ve forgotten the terrain.
Future You Is a Stranger
Assume you’ll forget:
- Which config file controls what
- How you deployed that Hugo theme
- Where the backup script logs live
Write for the version of you waking up at 3 a.m. trying to fix something half-asleep.
Minimum Viable Docs
You don’t need corporate templates. A handful of plain text files work:
- README.md at the root of each project: what it does, how to deploy, where the secrets live
- ops.md: backup and restore steps, restart commands, monitoring checks
- infra.md: network layout, hardware specs, DNS records
Small, boring, and clear beats perfect.
Embed Docs Close to the Work
Docs that live far away rot.
Keep them in the repo with the code or configs.
Update as part of your workflow — if you change a deploy script, update the line in the README.
Write the Why, Not Just the What
Future you doesn’t just need commands; they need context:
- Why did you pick this reverse proxy?
- Why does the cron job run at 2 a.m.?
- Why does this service have an odd port?
Decisions without reasoning are traps when you need to change them later.
Automate Where Possible
Use scripts to generate parts of your docs:
make statusthat outputs current versions and backup states- A cron job that dumps config summaries for review
Docs that update themselves stay more accurate.
Boring Is Beautiful
Good docs aren’t literature.
They’re survival kits.
If you can hand them to someone else (or future you) and they can bring the system back from cold, you’ve done enough.