Technical documentation fails in a specific and predictable way. Somebody writes a great deal of it during a quiet fortnight, the system changes, nobody updates it, and within a year the document is confidently wrong. At that point it is worse than nothing, because a reader who trusts it acts on information that no longer holds.

The usual response is a push to write more, which accelerates the same failure. The useful response is to write less and choose what, because the constraint is not authoring effort. It is maintenance.

The only durable test for whether a document should exist: will somebody notice when it becomes wrong? A deployment guide gets used and its errors surface immediately. A twenty-page description of a subsystem gets read once, and its errors surface eighteen months later when somebody acts on it. Documents nobody exercises rot silently, and those are the ones to leave unwritten.

Why It Goes Stale

Three mechanisms, and only one of them is laziness.

Documentation lives away from the thing it describes. A change to the code is not a change to a wiki page, so keeping them aligned depends on somebody remembering. That memory fails, reliably, and the further the document sits from the code the faster it goes.

It describes implementation rather than intent. A document explaining how a component currently works is invalidated by every refactor. One explaining why the component exists and what constraint it satisfies survives, because the reason changes far less often than the code.

Nobody owns it. Documentation owned by everybody is owned by no one, and there is no moment at which its accuracy is anybody’s problem.

The fixes follow from the causes: keep it close to the code, write intent over mechanism, and give each document a named owner and a reason somebody exercises it.

The Technical Documentation Worth Maintaining

Four documents cover most of the value. Everything else should have to justify itself.

A README that gets you running. What this is, how to set it up, how to run the tests, how to deploy. Exercised constantly, so errors surface fast. This is the highest-return document in any repository and the one most often left as a project template nobody edited.

An architecture overview. What the major pieces are, how they communicate, and why they are separated. One page and a diagram, describing shape rather than detail. It changes rarely and answers the question every new engineer otherwise reconstructs by reading everything.

Decision records. Short notes capturing a decision, the alternatives considered and the reason. These are append-only, never need updating, and prevent the most expensive kind of repeated work: re-arguing a settled question badly because nobody remembers the constraint that settled it.

Runbooks for things that break. How to diagnose and fix the failures you have actually had. Written after an incident while it is fresh, and exercised at the next one. A runbook nobody has followed is a draft.

Notice that none of these is a description of how the code works. That is what the code is for, and any prose duplicating it becomes a second source of truth that will disagree with the first.

Write for Somebody Tired and in a Hurry

Most technical documentation is read under pressure, by someone with a specific question, often outside working hours. Write for that reader rather than for a leisurely one.

Answer first, explain after. The person reading your runbook at two in the morning needs the command, then the reasoning. Context before answer is a structure that suits the author and nobody else.

Be concrete. Real commands, real paths, real example values. “Configure the appropriate environment variables” is not instruction, it is a description of instruction.

Say what will go wrong. The failure modes and what they look like are frequently the most valuable content, because they are what the reader is actually experiencing.

Keep it short enough to stay true. Every sentence is a maintenance liability. A page that covers the common case and admits its own limits beats a document that covers everything and is wrong in three places.

The same discipline that makes a page quotable to a retrieval system makes it usable to a tired colleague, which is the point our guide to why content ranks but never gets cited makes about public writing.

Keeping It Alive

Put it in the repository. A document that travels with the code is changed in the same review as the code, which is the only mechanism that reliably keeps the two aligned.

Review it in code review. If a change makes a document wrong, that is a review comment like any other. This is the single highest-leverage habit available and it costs nothing.

Test what you can. Setup instructions that run in a pipeline stop being aspirational. If your README claims three commands produce a running system, have a job prove it.

Delete aggressively. A wrong document is worse than a missing one, because it is trusted. When something goes stale and nobody will fix it, remove it and note what was lost.

Date the things that expire. Anything with a version number, a price or an external dependency should carry a date, so a reader can judge whether to trust it.

What This Is Really For

Documentation is the mechanism by which knowledge stops depending on individuals. That is the entire benefit, and it is why the argument for writing it is a business one rather than an aesthetic one.

A system only one person can deploy has a recovery time equal to that person’s availability. A component nobody can justify gets rebuilt or preserved on superstition. Both show up as findings in technical due diligence, both extend developer onboarding, and both are the same problem wearing different clothes.

Mecanik writes this as part of handover on every engagement, as part of our software development work. The document that gets used is nearly always shorter than the one that was requested.

Frequently Asked Questions

Why does technical documentation go out of date? Because it lives away from the code, so alignment depends on somebody remembering; because it describes implementation rather than intent, so every refactor invalidates it; and because nobody owns it, so its accuracy is never anybody’s specific problem. Keeping it in the repository and reviewing it alongside code changes addresses all three.

What documentation should a software team maintain? Four things cover most of the value: a README that gets the system running, a one-page architecture overview explaining shape and reasoning, append-only decision records capturing why choices were made, and runbooks for failures you have actually had. Descriptions of how the code works are not on the list.

What is a decision record? A short note capturing a decision, the alternatives considered and the reason for the choice. Because it records a moment rather than a current state, it never needs updating, and it prevents settled questions being re-argued badly by people who no longer remember the constraint that settled them.

How should technical documentation be written? For somebody tired, under pressure and looking for one specific thing. Answer first and explain afterwards, use real commands and real paths rather than descriptions of them, say what goes wrong and what it looks like, and keep it short enough that it stays true.

Should out of date documentation be deleted? Yes, if nobody will fix it. A wrong document is worse than a missing one because a reader trusts it and acts on it. Delete it and note what was lost, and date anything containing a version number, a price or an external dependency so readers can judge it themselves.