Write the owner's manual from the running system

Most documentation I've inherited was written from memory. Someone sat down after a project, described how they thought it worked, and moved on. A month later the system had changed and the document hadn't. A year later the document was actively misleading, which is worse than having nothing at all.

For each major system I run, I keep an owner's manual. What makes it different is where it comes from. I don't write it from memory. I write it from the output of an inventory script that reads the live system: the files that exist, the scheduled jobs that are actually registered, the tables in the database, the services that are running. The script tells me what's there. The manual explains it.

A map, not a copy

The first rule is that the manual is a map. It doesn't paste in config files or list every setting. It tells you what exists, what each piece is called, what it's for and where to find it. If you want the exact value of something, the manual points you to the place that holds it.

This keeps the manual small enough to stay true. Every copied detail is a detail that can go stale. A map only goes out of date when the territory changes shape, and that's exactly when you should be updating it anyway.

One fact lives in one book

I keep separate kinds of documents and I don't let them overlap. The manual says what exists and what it's called. A register says what's running right now. A pattern library says how we build things. Each one answers its own question and links to the others for everything else.

When the same fact lives in two places, the copies drift apart, and then nobody knows which one to trust. So every fact has a home.

Counts are the classic trap. Writing the number of scheduled jobs into a paragraph feels helpful. It's wrong the week someone adds one. Counts in prose go stale, so I don't write them. I link to the inventory, which does the counting fresh every time you look.

Honest chapters

A chapter may say "not yet true." It may never say something works when it doesn't.

That rule sounds small. It changed how I write. When a feature is half built, the chapter says so plainly, along with what's missing. When something is designed but not wired up, the chapter says exactly that. A reader should never find out from an outage that the manual was describing a hope.

And if the book and the disk disagree, the disk is right. Every time. The manual is a description of reality, so when the two conflict I fix the manual and then ask why nobody noticed sooner.

Every chapter has the same sections

Consistency makes a manual easy to scan, and it makes gaps obvious. Every chapter I write has these sections, in this order:

1. Name and aliases. The one name we use, plus any other names people have called it.
2. Job. One sentence on what it does.
3. Owns. The records, files or decisions that belong to it.
4. Does not own. The things people assume it handles but it doesn't.
5. Where it lives. Paths, hosts, tables.
6. What feeds it. Its inputs and where they come from.
7. How it fails. The ways it breaks, especially the quiet ones.
8. What proves it works. The check you'd run to know it's healthy.
9. Owner and gaps. Who's responsible, and what's still missing.

"Does not own" is the section people want to skip, and it's one of the most useful. A lot of confusion in any system comes from assuming a component does something it was never built to do. Writing down the negative space saves arguments later.

"How it fails" and "what proves it works" force their own kind of honesty. If you can't fill them in, you don't really understand the system yet. Better to learn that while writing than during an incident.

Keep it true with a drift check

A manual written from the live system is accurate on the day you write it. To keep it that way, I run a drift check. It compares what the manual names against the real files, jobs and tables. If the manual mentions a job that no longer exists, that's drift. If a new table shows up that no chapter claims, that's drift too.

The second kind is the one I care about most. Things that exist without documentation are things nobody owns. The drift check surfaces them while they're still small and easy to deal with.

One more rule. Versions bump in the same session as the change. Not later, not at the end of the week. If I change a system and don't update its chapter before I close the session, the odds of coming back to it drop fast. The change and the documentation go out together, or the change isn't finished.

How to start with one system

You don't need to document everything at once. Pick the system you'd least like to explain from scratch in the middle of the night.

1. Write a small script that lists what actually exists. Files, scheduled jobs, database tables, running services. Save its output somewhere you can link to.
2. Draft one chapter using the nine sections above, working only from that output. If you remember something the script didn't find, go check before you write it down.
3. Mark anything unfinished as "not yet true." Be blunt about it.
4. Replace every count in your prose with a link to the inventory.
5. Decide where each fact lives. If it belongs in a register or a pattern library, move it there and link to it.
6. Set up a simple comparison between the chapter and the inventory, and run it on a schedule.
7. Make "update the chapter" part of the definition of done for any change.

The first chapter is the slowest. After that you have a template and a script, and each new chapter is mostly filling in blanks. The hard part is the discipline in step seven, and that gets easier once you've been saved by an accurate manual even once.

This connects to something I've written about before, inspecting the system before the symptom. An accurate manual is what makes that inspection fast. You start from a map you can trust instead of rebuilding one under pressure.

A manual written from memory tells you what someone believed on the day they wrote it. A manual written from the running system tells you what's there. When something breaks at a bad hour, only the second one is any help.