The only person who understood it has left

Documentation decays. Code does not.

A wiki page is a claim about the system. The code is the system.

The two diverge from the moment the page is written, and nothing in a normal delivery process forces them back together. The diagram is not wrong because somebody was careless — it is wrong because the diagram and the thing it describes are maintained by different people, at different times, for different reasons.

Documentation is a snapshot of what somebody believed. The repository is a record of what was actually done.

Which is why the honest first step in inheriting a system is not “read the docs”. It is “trust nothing you cannot trace to a file”.

Three ways to end up here

The same problem arrives from three directions, and the panic feels identical in all of them:

• Attrition — the engineer who held the model of the system in their head has gone, and the handover was two weeks of meetings and a folder of screenshots
• Inheritance — an acquisition, a supplier change or a reorganisation has left you owning a codebase nobody in the building wrote
• Migration or redesign — the system has to change, and nobody can say with confidence what depends on what

In each case the missing artefact is the same: a current, evidence-linked map of the architecture, the data models, the APIs and the flows between them. Not somebody’s recollection of it, and not a diagram drawn from that recollection.

What a repository can tell you about itself

A codebase is not a mystery. It is an under-read source of fact. A structural analysis of one produces an inventory rather than an opinion:

• Architecture — the components, layers and boundaries that actually exist, rather than the ones on the whiteboard
• Data models — entities, fields and relationships, read from the schema and the code that touches it
• APIs — the routes exposed, what they accept and return, and which of them nothing has called in two years
• Dependencies — internal and external, including the ones nobody remembers adding
• Application flows — the path a request actually takes, end to end, through the layers that are really there

A scan reporting 26 source files, 2,185 source lines, 158 graph nodes and 254 relationships is not a summary. It is an inventory, and every item in it points back at a line you can open.

The unglamorous numbers matter too. Which files were excluded and why. Which branch was scanned. Which parser version produced the graph. A snapshot you cannot reproduce is an anecdote.

Evidence-linked, or it is just a plausible summary

This is the distinction that decides whether generated documentation is useful, and it is where most tooling in this space falls down.

A language model asked to describe a codebase will produce something fluent, structurally reasonable and impossible to verify. It will also be confidently wrong about the parts it inferred rather than read — and nothing in the output tells you which parts those were.

The alternative is a deterministic source graph underneath, with the model used to explain what the graph found rather than to guess at what the code does. Every claim carries a pointer: this component, from these files; this relationship, from this call; this entity, from this schema.

If a statement cannot be traced to source, it should not appear. That single constraint is the difference between documentation you can put in a migration plan and documentation you can only put in an onboarding deck.

Nothing publishes without a human

Generated documentation that publishes itself is simply a new kind of debt — now with the authority of looking official.

The pipeline that avoids that is deliberately unexciting: connect the source, confirm scope and policy, analyse, review the evidence, then publish. And publishing is its own decision — a space, an owner, named reviewers, a classification and a lifecycle state, all chosen before anything is saved.

The review step is not ceremony. It is where somebody who knows the business decides that a technically accurate description is also a true one. The graph can tell you a service exists and what calls it. Only a person can tell you it was deprecated last quarter and the replacement is half-built.

What changes on the three bad days

On the day someone leaves, the handover stops being a calendar problem. The structural knowledge is already extracted and reviewed; what the departing engineer owes you is the reasoning, the history and the warnings — the things a graph genuinely cannot hold.

On the day a migration is scoped, the plan is built on a dependency graph rather than a workshop. The estimate changes, because the surprises that normally arrive in month three arrive in week one, when they are still cheap.

And on the day a redesign is proposed, the argument moves from opinion to evidence. Everybody in the room is looking at the same map, and the map can be checked.