Documentation Is Infrastructure

Documentation gets filed under “nice to have,” somewhere below the real work, to be done later if there’s time. There’s never time. I want to argue for a different filing: documentation is infrastructure. It’s not the description of the system — for anything secure, automated, or built with agents, it’s load-bearing part of the system. Pull it out and things fall over, just on a delay long enough that you forget what caused it.

I’ll keep the examples generic on purpose. The point isn’t any particular runbook; it’s the shape of the habit.

Docs are operational memory

A system’s behavior lives in two places: the code, and everything the code doesn’t say. Why this timeout is 30 seconds and not 5. Which of two plausible designs you picked and what the loser cost you. That second place is real, it’s operationally critical, and by default it lives in exactly one human’s head.

Undocumented context isn’t institutional knowledge. It’s a single point of failure that happens to be a person.

Operational memory is what lets you act under stress without re-deriving the whole system first. Without it, every incident starts with archaeology, and archaeology is the last thing you want to be doing while something is on fire.

Docs are a security control

This is the one people resist, so I’ll be direct: writing things down is part of how a system stays secure. Not paperwork about security — the actual control surface.

• A trust boundary you can’t point to is a trust boundary you can’t defend.
• An access grant nobody wrote down is an access grant nobody will ever revoke.
• A recovery procedure that only exists in someone’s memory is a recovery procedure you don’t really have.

You can’t reason about an attack surface you can’t see in one place, and “in one place” means written down. The discipline I lean on in the homelab — segmentation, least privilege, secrets that live in managed storage and never in a screenshot — is only auditable because it’s documented. An undocumented secure system is just a system you’re hoping is secure.

Docs are the onboarding surface

Every system has a moment where a new person — or a new you, six months on — has to get productive without the original author hovering. Docs are the surface they land on. Good ones turn a week of nervous spelunking into an afternoon; bad ones turn a simple change into a ritual that only the high priest can perform.

The tell is the bus-factor question: if the person who built this vanished tomorrow, could someone competent pick it up from what’s written? If the honest answer is no, the docs aren’t thin — the system has a staffing dependency disguised as a technical one.

Docs are guardrails for AI agents

This one is newly load-bearing. When an agent does a chunk of the building, the documentation isn’t a report you write afterward — it’s an input the next slice depends on. A model can’t infer your intent from silence any more than future-you can at midnight.

So the things that travel get written where they’ll be read: what the boundaries are, which paths are off-limits, what “done” means for this codebase, why a tradeoff went the way it did. On this site that lives in a couple of always-loaded files the agent reads first, and it’s the difference between an agent that respects the architecture and one that cheerfully reinvents it three different ways. Docs are how each slice starts from solid ground instead of re-litigating the whole design — which is the same loop I lean on across the AI automation work.

Docs are future-you protection

Strip away the professional justifications and there’s a selfish one underneath that I find more honest: future-me is a stranger with none of today’s context, and documentation is how I stay on speaking terms with him. He will not remember why the config is shaped like that. He will be tired, it will be late, and something will be broken.

Write the doc for the version of you who is exhausted, under pressure, and has forgotten everything. That person shows up eventually, and they deserve better than your memory.

That framing also keeps docs honest. You don’t write essays for that person — you write the few things they’ll actually need: where the bodies are buried, how to recover, what not to touch. Docs as infrastructure doesn’t mean more writing. It means writing the load-bearing parts and skipping the ceremony.

Build the docs in, not on

The practical upshot is to treat docs the way you treat any other part of the system: built in, not bolted on. A change isn’t done when the code works — it’s done when the next person, human or agent, can operate it without you in the room. That’s an architecture standard, not a nicety, and it’s the same instinct behind everything on the work page. If your systems only run because you personally remember how, you don’t have systems yet — you have a very elaborate hobby. If you want to trade notes on making docs actually pull their weight, my inbox is open.