The day the person who knew leaves
Almost every organisation has a system that works and that nobody dares touch. It works because somebody designed it well. Nobody touches it because that somebody is no longer around, or is on something else, and what they knew was never written down.
That is the most common architecture failure, and the least visible. It does not show up on any monitor. It shows up when something has to change and nobody can explain why it was built that way, what breaks if it is touched, or what it really costs.
What makes an architecture survive
An architecture that depends on nobody has four things, and none of them is technological:
- Written decisions. Every relevant choice, with its context, the alternatives that were ruled out and why. Not the what, which can be seen in the code, but the why, which cannot be seen anywhere.
- Explicit requirements. What availability it needs, how much data it can afford to lose, how much it can cost. Without that, nobody can tell whether a change improves or worsens the system.
- Documentation that maintains itself. Diagrams and descriptions generated from the same source as the system, so they do not age in the first month.
- A standard to compare against. A written organisational standard that makes it possible to review any design against criteria rather than opinions.
Why it does not get done
It does not get done because writing decisions down feels like wasted time while everything is still fresh in your head. The cost shows up months later, when nobody remembers anything, and somebody else pays it. It is the same pattern as technical debt, but with knowledge.
The good news is that the effort is small if it is done at the time: a written decision takes minutes on the day it is made and weeks on the day it has to be reconstructed.
What this series is about
This series walks step by step through how a cloud architecture is designed, documented, validated and operated so that it outlives whoever built it: from writing down decisions and requirements to designing by zones, choosing between a monolith and microservices, handling data, documenting as code, surveying what was inherited, reviewing against a standard, estimating cost and designing for failure.
How we apply it: Cloud Architecture.