When nobody can describe the system you have inherited
The documentation problem is rarely that nobody wrote anything. It is that what was written stopped being true, and everyone learned not to trust it. Starting again by interviewing people reproduces the same failure a year later.
The situation
Somebody left, or a system was acquired, or a project ended and the team moved on. What remains is a running system, a repository, a database, and a set of half-remembered explanations that contradict each other in the details that matter.
The instinct is to book a week of workshops and draw what people say. That produces a diagram that is accurate on the day of the workshop and wrong within a quarter, because it was derived from memory rather than from the system.
The alternative is to derive the first draft from artefacts that cannot be wrong about themselves — the schema, the repository, the file formats the previous team left behind — and to use people to correct that draft rather than to produce it. Correcting a wrong diagram is a far easier conversation than producing a right one from nothing, and it takes an hour rather than a week.
You are here if
- The most recent architecture diagram you can find is a slide, and nobody will say whether it is still accurate.
- The database has tables whose purpose is disputed.
- Onboarding a new engineer takes months and is done entirely by conversation.
- A change was made recently that broke something nobody predicted it would.
How the work gets done
Start from the artefacts, not from memory
Import the database schema and let the tables, columns, keys and constraints become the first version of the model. This is the part of the system least likely to be lying to you: a foreign key is a fact about how the data is actually related, regardless of what anyone believes.
If the schema lives in a running database rather than a script, read it directly. If it lives in a Mermaid diagram in somebody’s README, that imports too. The point is to get the structure in without retyping it, because retyping is where the errors and the abandonment both come from.
Data ▸ Import DDL / Mermaid ERData ▸ Live DB ImportData ▸ Import CSV / Excel
Bring in what the code says about itself
Generate the component view from the repository, so the services and their dependencies come from the code rather than from a whiteboard. The result will not be complete and will not be pretty, but it will be true in the specific way that matters: it reflects what is deployed, not what was intended.
Where the generated picture and the remembered picture disagree, the disagreement is the finding. That is usually the most valuable output of the first week.
Use people to correct, not to produce
Put the imported model in front of the people who know parts of the system and ask them what is wrong with it. This inverts the usual workshop: instead of asking someone to recall an architecture, you are asking them to react to one, which is a much more reliable operation on human memory.
Record what you do not know as notes on the diagram rather than leaving gaps. An explicit "nobody knows what writes to this table" is documentation; a blank space is not.
Page ▸ NoteDiagram ▸ Team & collaborators
Make it hard for the model to go stale
The reason the last documentation died is that nothing connected it to the system. Put the model under version control alongside the code, so a change to the architecture is a reviewable change rather than an edit nobody sees.
From that point the model answers questions — what depends on this, what would this change break — which is what keeps people opening it. A document that answers questions gets maintained; a document that only describes does not.
Arch ▸ GitHubData ▸ Impact Analysis
What you end up holding
- A model of the data structures derived from the real schema, with the relationships the database actually enforces.
- A component view derived from the repository, and a list of the places where it contradicts what people believed.
- A written record of what remains unknown, visible on the diagram rather than in someone’s head.
Not this, if
- The system is being decommissioned within the year. Document what is needed to switch it off, and do that in a page of text.
- You need documentation for a compliance deadline and nothing more. A point-in-time export is cheaper, and this approach is aimed at documentation that keeps working.
- The system has no database and no repository you can read — an entirely third-party estate, for example. There is nothing to derive the first draft from, and this becomes an interview exercise after all.