Documentation as Infrastructure

In an office, undocumented knowledge is expensive but survivable — you ask the person. Remotely, asking costs a day, and if they are unavailable, several. Documentation stops being tidiness and becomes operational infrastructure.

What actually needs writing down

Not everything. The instruction to "document everything" produces a wiki nobody maintains and nobody trusts.

Four categories earn their upkeep:

Decisions. What was decided, when, by whom, why, and what was rejected. The rationale matters more than the decision, because the decision is usually discoverable from the system and the reasoning never is.

How things work. The architecture, the process, the sequence of steps. Specifically the parts that are not obvious from looking.

Ownership. Who is responsible for what, and who to ask about what. In a distributed team this is the most frequently needed and least frequently written information.

Norms. The unwritten rules — response times, meeting conventions, what urgent means. Half a page, and it prevents dozens of small misunderstandings.

Everything else can usually wait until someone asks twice.

The maintenance problem

Documentation rots. A wiki full of pages last edited three years ago is worse than no wiki, because people cannot tell which pages are still true, so they trust none of them.

Three habits keep it usable:

Date and owner on every page. Not for bureaucracy — so a reader can judge how much to trust it.

Delete aggressively. A page nobody has opened in a year and nobody will defend should go. The instinct to keep everything is what produces the untrustworthy pile.

Update as part of the work. A change that alters how something works includes updating the page. Not a follow-up task; part of the same task.

Write for the person who is stuck

The reader is not browsing. They have a problem, they are blocked, and they are looking for one specific thing.

Lead with the answer. Then the caveats. Reversing this is the most common flaw in internal documentation.

Say when it does not apply. Boundary conditions save more time than the happy path.

Include the thing that went wrong last time. The most valuable sentence in most internal documents is a warning about a specific failure.

Name people and teams, not roles that changed two reorganisations ago.

The decision record

If you adopt one practice, adopt this.

A short standard note for each significant decision: the context, the options considered, the decision, the reasoning, the date, the person accountable. Half a page, kept where it can be found.

The payoff arrives eighteen months later when someone asks why the system works this way. Without a record, the answer is either a guess or an archaeology exercise across chat logs. With one, it is a link.

It also prevents the same argument recurring annually, which in most organisations it does.

Who writes it

The failure mode is expecting documentation to happen in spare time. There is no spare time.

Make it part of the task. A change is not finished until the page reflects it.

Give a page an owner, not the team collectively. Collective ownership of a document means nobody owns it.

Have new joiners fix what confused them. They are the only people who can see the gaps, and the window closes within a month. This is the highest-yield documentation practice available and it costs nothing.