Documentation Culture: Building Your Team's Second Brain

We used to be a team that ran on oral tradition. The deployment process lived in one person's head, the quirks of the payment integration in another's, and the answer to "why was it designed this way?" lived wherever everyone had forgotten it. It was fine — until a key team member took a long vacation, a routine deployment got stuck, and the whole team sat staring at the screen guessing where the passwords were kept. What we lost that day wasn't time. It was trust in ourselves.

Since then, documentation went from "something we'll write when we have time" to infrastructure. This article isn't going to tell you "documentation matters" — that's empty. It's about how we actually write it, where we keep it, and how we stop it from rotting — because documentation's biggest enemy isn't that nobody writes it; it's that nobody updates it, until it becomes a pile of beautiful lies.

The Three Kinds of Documents We Write

We don't write everything down. Writing too much is as bad as writing nothing — both make people give up on reading. We maintain only three kinds:

1. Decision records: every architecture-level decision — why this technology, why this data flow — gets a one-page write-up covering the context, the options, and why we chose what we chose. The key rule: when a decision is overturned, we don't edit the old document — we write a new one and mark the old one "superseded." Three years later, someone can see the full trail of thinking, not just an unexplained status quo.
2. Runbooks: deployment steps, restore procedures, reconciliation methods, handling for common failures. The test is simple: if only one person knows how to do something, the company owes itself a document.
3. Handoff snapshots: each project keeps a living document of "where we are, what's blocked, what's next." It doesn't just save departures and handovers — more often it saves your own future self, coming back to the project three weeks later having forgotten everything.

Where It Lives: With the Code

Putting documentation in a separate cloud drive or wiki is where the rot begins — because the person changing the code never passes by it. Our approach: documentation lives in the code repository itself, gets updated in the same commit as the feature change, and gets reviewed together with it. The responsibility for updating a document belongs to whoever made the change — not to some "person in charge of documentation." That person does not exist; counting on them is counting on decay.

Good documentation is the team's second brain: the first brain quits, takes vacations, and forgets. The second one doesn't.

What This Means for Business Owners: Documentation Is an Asset, Not a Chore

If you're the client commissioning a system, this concerns you even more. At delivery, you should receive more than a URL and a set of credentials — you should get complete documentation: an architecture overview, a deployment manual, a list of third-party services. A system without documentation is, in practice, held hostage by its original vendor — not because they mean to hold you, but because nobody else can pick it up. The day the relationship changes, your system becomes an orphan. We go deeper on this in our piece on handover terms.

On quality, one sentence covers it: write for your amnesiac self three months from now. It doesn't need style or completeness — it needs to let a reasonably capable person with zero context walk through it end to end. The test is just as simple: hand the document to someone who's never touched the task and have them follow it. Every place they get stuck is a hole in the document. Every drill we run finds holes, and every time we're grateful we found them in a drill — not in the middle of the night with something on fire.

Honestly, writing documentation is still the thing that demands the most discipline on our team. It is never urgent; it can always wait until tomorrow. Our solution is to bind it into the process: a feature isn't done until its documentation is updated. Not self-discipline — systems. That's probably the only method that works.