Short answer
#The Friday phone call
Friday, around six. The call is from the large customer, the one the last four months of conversations have been about. They have a new lawyer, and the lawyer wants one thing: where their employees personal data physically sits, and who else can see it.
You know the slogan version of the answer. Everything is in Europe, everything is encrypted. The lawyer needs the other version: the list of places that data ends up in, including backups, logs, the mail provider, and that analytics service somebody connected eighteen months ago. One person on the team has the exact answer. That person is away until Wednesday.
What happens next is the expensive part, and it is not a lost deal. It is a pause: five working days in which you cannot say anything definite about your own product. And somewhere in those five days you notice that the question was never technical. It was about who you belong to.
What this is about
Not that developers are careless or that documentation should be written more neatly. That a business question about your system has no source of answer other than a person, and that this stopped being normal recently.
#The scarcity moved
Over the last two years the idea that a software business is not built out of code has become common ground. Founders who sold a company repeat it, and so do founders who sold nothing. The point is simple: the winner was not whoever wrote the best product, it was whoever reached the people with the problem first. Code turned out not to be the advantage.
I agree with that. What happens next is that a correct observation is turned into a wrong conclusion: if code is not the advantage, then code can be left alone. The owner hears “the business is relationships” and decides, with some relief, that the technical half is no longer theirs.
Code stopped being the advantage, because everybody can get it now. It did not stop being the constraint, because the business walks into it at the least convenient moment, and the owner does not pick the moment. Three things changed at once, and all three work against you.
-
There is more software per person
One developer with an agent produces in a week what used to take a month. The number of services, integrations and scheduled jobs in the system goes up. The number of people who hold it in their heads does not.
Volume grows faster than the ability to explain it.
-
Understanding stopped arriving for free
Writing a module used to force somebody to understand it, and the understanding stayed behind as a by-product of the work. Now the work happens in sessions. The session ends, and so does the understanding.
This is not about code quality. A quality review is powerless here: the code can be good and the explanation can be absent.
-
People change more often than systems
A product lives five or ten years. The developer, the agency and the technical lead each change several times inside that. Every departure takes a piece of the picture, and nobody measures which piece.
The system stays. Knowledge of it leaves in instalments.
The result is an unpleasant symmetry. Production got cheaper, understanding did not. The faster you ship, the faster the part of your product grows that nobody in the company can answer a single question about.
#The gap widens on its own
Draw two lines from one starting point. The first is how much the system contains: components, integrations, places data is kept, jobs on a schedule. The second is how much of that somebody can explain and point at. The first line accelerated. The second moves at the speed of a person reading, asking and remembering, and that speed did not change.
Every uncomfortable conversation lives in the space between the lines: due diligence, changing supplier, the question about personal data, an estimate somebody has to commit to.
This gap has a property that keeps it from being noticed in time: it does not stop anybody working. The product runs, the team is in place, tickets close. The gap only speaks up when somebody outside asks a specific question. Which means it is discovered in the worst available circumstances: in a negotiation, during a handover, in the middle of an incident.
I see it on my own work. 1ADK is covered by more than a thousand automated tests, it has its own documentation, and I wrote it. The first time I ran my own analysis over it, the picture still contained things I could not have named from memory: dependencies between parts that I remembered differently, and places where the honest answer was that nothing was established. If that is the position of the author of a system, the owner of one they did not write is an order of magnitude further out.
#What gets spent while you wait
The gap never invoices you, which is why it appears in no budget line. It spends four other things, and all four are finite.
- Time to a decision. Any question that needs knowledge of the system turns into waiting for a person. Not an hour of work: a date. By Wednesday, by the end of the sprint, when somebody is back.
- Money for finding out again. Every newcomer rebuilds the picture from nothing at full rate. A new agency, a new technical lead, an auditor, each one from the start.
- The freedom to change team. The less you understand, the more expensive a change of supplier is, and the weaker your position when price comes up. Dependency rarely looks like a conflict. It usually looks like agreeing to terms you would have argued about if you had a choice.
- A buyer trust. An enterprise customer, an investor and an acquirer ask the same questions and draw the same conclusion from "we would need to check with the developer".
Two scenarios, in terms of what will actually happen rather than catastrophe: change nothing and keep answering through people, or get a checkable picture once and keep it.
| Moment | Leave it as it is | Deal with it now |
|---|---|---|
| In three months | A few more integrations and scheduled jobs exist. The list of what runs on a schedule lives in somebody memory. | The list exists, and what changed this quarter is visible. New questions close in minutes. |
| In a year | One of the key people has moved on. Some decisions are now explained with the words “that is historical”. | A departure costs the time to replace a person, not the cost of rebuilding the picture of a product. |
| An enterprise customer with requirements | The security questionnaire becomes a week of internal messages and carefully hedged wording. | You answer most of it yourself, and say where each answer comes from. |
| Changing supplier | The handover takes months and is paid for twice: to the outgoing team for explaining, to the new one for learning. | What changes hands is not only access but a description of the system the new team can check. |
| A sale or a round | Technical due diligence finds something you did not know about. The price is discussed again. | You present the picture yourself, including the list of known weak spots. That is a different conversation. |
The right-hand column does not promise there will be no problems. It promises you will hear about them first and from yourself, rather than last and from a buyer.
#What to do about it
The good news is that the job is finite. You do not need to understand the code. You need to be able to get answers to business questions without one specific person. That is measurable, and there is an order to it.
-
Write down decisions, not topics
Three or four decisions in the next quarter that need knowledge of the system. Raise a plan price. Take on an enterprise customer with their requirements. Change supplier. Split a piece of functionality out.
A topic sounds like “architecture”. A decision sounds like “can we promise EU-only storage by March”.
-
Turn each decision into a question about the system
Not “tell me about the architecture”, but “which services does customer personal data pass through”, “what breaks if we switch off the old payment provider”, “what runs on a schedule and what would notice if it stopped”.
A question nobody can answer in one sentence usually means nobody has been asked it before.
-
Find out who answers
Ask those questions in a way that does not route through one person. Look for the answer in documentation, in a description of the system, in a tool. Count how many closed without calling a developer.
That count is your dependency today. It is enough to tell you whether you have a problem.
-
Get one checkable picture
A description of the system where every claim shows where it came from and every gap has a name. What is unknown has to stay unknown rather than becoming a confident paragraph.
A picture with no references reads like documentation and behaves like a rumour.
-
Keep it in step with the system
One analysis goes stale exactly as documentation went stale. The value arrives on the second and third one, when the difference is visible: what was added, what disappeared, where it got worse.
A repeat analysis answers the question a single one cannot be asked: what changed while I was not looking.
-
Measure dependency, not volume of documentation
A bad metric: how many pages of description exist. A good one: what share of questions about your product you can close without a particular person, and how long it takes.
The first grows by itself and means nothing. The second only moves when something really changed.
#A twenty-minute test
Before changing anything, measure where you stand. Answer these yourself, without asking the team. What matters is not the score but how often you catch yourself saying “I would have to check”.
Six questions for an owner
Three “I would have to check” out of six means this page is about your system.
- Name every place your customers personal data ends up, including copies and external services. This is the first question from an enterprise customer and the first question from a regulator.
- List everything that runs on a schedule, and say who finds out if it stops. A job that stops quietly is discovered from outside, months later.
- Name the external services you depend on, and what happens when each one goes away. The most expensive surprises during a price change or a provider change live here.
- Say what changed in the structure of the system last quarter. Not in tickets and releases, in the system itself. Usually nobody knows this.
- Say who, besides one person, can answer the previous four questions. That is your dependency, expressed as a number of people.
- Say where the answer is written down if that person is not here tomorrow. If the answer only exists in a head, you do not have an answer. You have a person.
#What people do instead
Commission a large technical audit once a year.
Instead An audit answers the questions of the day it was done. A quarter later the system is different and the report is not. What is needed is a picture that can be refreshed and compared with its previous version.
Have an agent generate documentation and file it in a shared folder.
Instead Generated text is smooth and indistinguishable from checked text. Require a reference under every claim, and a separate list of what could not be established.
Appoint somebody responsible for documentation.
Instead The responsible person leaves with the documentation and you are back where you started. The responsible party has to be a mechanism: the description is refreshed by the same work that changes the system.
Decide to sort it out before the next big event.
Instead A big event is the worst moment: no time, and somebody else deadlines. Sort it out on a quiet week, when a mistake costs nothing.
Assume it is enough to ask an AI assistant when the need arises.
Instead You can ask, and the answer will be reasonable. But the second time the answer is different, the two cannot be compared, and no record is left of which one was right and when.
#What this does not solve
Understanding your system is a condition for good decisions, not the decisions themselves. Plainly, what it does not give you.
What this does not do
- It does not replace a team. Knowing how a system works and being able to change it are different skills.
- It does not make a decision right. An exact answer about data storage will not tell you whether to take that customer.
- It does not assess code quality. A picture of a system says what exists and what is connected, not how well it is written.
- It does not cancel trust in people. The goal is not control over a developer, it is that the conversation has two sides who each hold a picture.
- It is never complete. Some things stay unknown, and in an honest picture they are labelled that way.
And the last thing, which is the whole point. The question is not whether your code is good or bad. The question is how many people have to be reachable before you can make a decision about your own product. If the answer is one, that is your constraint, and it has nothing to do with who wrote the code: a person, an agency, or an agent.
Who in your company could answer all six questions from the test above today, and what happens to those answers if that person leaves next month?