Why does technical documentation always go out of date?

#Why documentation decays

Four mechanisms, none of which can be fixed by trying harder.

1. It is a copy of something that moves

   A page describing a system is a snapshot taken by hand. The system continues; the page does not. Nothing in the process connects the two, so the divergence is silent by construction.

2. The cost of updating it lands on the wrong person

   The person who could update it accurately is the person who just shipped the change, and updating it does nothing for them. This is not a character flaw — it is what happens to any task whose cost and benefit sit with different people.

3. Nobody can tell how stale it is

   A page with a date on it tells you when somebody edited it, not which of its sentences are still true. A document that is 80% correct is more dangerous than one that is obviously abandoned, because it is still believed.

4. The people who could fix it leave

   Understanding leaves with them, and the document stays — now unverifiable by anybody left. This is the point at which most companies discover what they actually had.

The consequence is a very specific and very common state: a company owns software it cannot describe, and owns a document describing software it no longer has.

#What a technical memory is instead

Technical memory

A maintained technical picture of a system: components, relationships, interfaces, data, the claims made about them, the evidence behind each claim, the open questions, and every previous version of all of it. Rebuilt from an analysis of the actual system rather than edited by hand.

In plain terms The company's own record of how its software is put together, kept current by being rebuilt rather than edited, and able to tell you what it no longer stands behind.

Three properties distinguish it from a document, and each one removes one of the four decay mechanisms above.

#Derived, not written

Nobody types a page into 1ADK. The picture is produced from an analysis, which means updating it costs one instruction rather than an afternoon of somebody's attention. That single fact is what makes the second update happen at all.

Because it is derived, it can also carry evidence: each claim names the file and lines it came from, so a reader can check it without asking the author. A hand-written page cannot do this, not because of tooling, but because the author was writing from memory.

And because every version is kept, staleness stops being invisible. The picture can say "this is what I told you in May, and I no longer support it" — see change history for how that works.

#It belongs to the company

This is the part that matters commercially rather than technically.

Understanding of a system is an asset. In most companies it is stored in working memory belonging to two or three people, which means it is not stored anywhere the company controls. It leaves with a notice period. It is unavailable during a holiday. It cannot be sold, audited, handed over or insured. And its owners are usually the least aware of how concentrated it is.

A technical memory moves that asset into something the company holds. Not completely — the reasoning behind decisions never fully transfers — but far enough that the difference is visible at the moments it counts: a handover, a supplier change, a new technical leader, a due diligence, an incident at 3am when the one person who knows is unreachable.

#This got worse, not better, with AI

A position worth stating plainly, because the obvious conclusion is the wrong one.

Coding agents make software much faster to produce. They also make an explanation of that software cheap to produce on demand — so it is reasonable to assume the documentation problem is now solved.

It is not, for two reasons.

• An explanation on demand is not a memory. An agent answering a question today holds nothing tomorrow. It cannot tell you what changed since last quarter, because it has never seen last quarter. Every answer starts from zero, and two answers a month apart cannot be compared.
• The rate at which understanding must be created has gone up. A system can now reach production having been written faster than anybody read it. The code is fine. What is missing is that no person ever held the whole picture — so there is nothing to go stale, because nothing was ever written.

The position 1ADK takes is not that this is bad. It is that understanding has to keep up with the speed at which software is now built, and doing that by hand is no longer possible. AI-built software deals with the owner's side of this properly.

#What it looks like in practice

• Analyse when something material changes — after a release, at the end of a contractor engagement, before a handover, when a new subsystem lands. Not on a schedule for the sake of one.
• Read the difference, not the whole thing. After the first analysis, the useful surface is what changed and what is no longer confirmed.
• Work the unknowns down. They are the shortest list of questions worth asking the people who still know.
• Point new people at it first. The map plus the open questions is a better first day than three meetings.

#When a wiki is still the right answer

A technical memory does not replace written documentation, and pretending otherwise would be a sales argument rather than a true one.

Anything that is a decision rather than a fact belongs in prose written by a person: why an approach was chosen, what was tried and rejected, what a constraint was, what the plan is. An analysis cannot recover any of that, and never will be able to.

The useful division: let the memory hold what is true, and let people write down why. Most companies today are attempting both by hand and managing neither.

#What it does not replace