Simplicity is earned, not declared
Every team claims to be simplifying. We refactor, automate, streamline, consolidate. The question is simple to ask and hard to answer: did we actually remove the complexity, or did we just move it out of sight?
Complexity rarely vanishes on its own. It migrates from interface to implementation, from one team to another, from the present into the future. Lehman wrote about this decades ago in his Laws of Software Evolution, noting that complexity increases unless active work is done to contain it. Left alone, entropy wins.
And now, with AI in the mix, hidden complexity does not stay hidden. It becomes the limit of what both people and machines can understand.
Complexity never really disappears
The law here is metaphorical, not physical, but it describes what we see in practice.
A clean API hides complex business rules. A single source of truth centralises data, then multiplies coupling. A crisp process reduces chaos, then adds meetings and friction elsewhere. This is displacement, not deletion. We have not destroyed complexity. We have relocated it.
Lehman’s perspective reminds us why this happens. As systems evolve, the pressure of real use and real change adds edges, exceptions, and integrations. Unless we actively design to counteract that pressure, complexity accumulates, not because anyone is foolish, but because reality is busy.
But some complexity can be killed
Not all complexity is forever. The craft is knowing how to remove it rather than disguise it.
Constraint. True simplicity often comes from choosing less. Opinionated defaults and limited options reduce the problem space itself. This is pruning, not hiding.
Abstraction. The right abstraction absorbs accidental complexity. Fred Brooks called this out in No Silver Bullet. High level languages removed machine level detail from everyday concern. Managed platforms removed much of server management. The complexity still exists, but no longer lives in your head or your backlog.
Reframing. Sometimes the original problem was misdefined. When you stop solving the wrong problem, an entire category of complexity dissolves. This is the rarest and most powerful move.
Simplicity is earned by design, constraint, and courage. It is not a slogan.
The two maps of knowledge
Every organisation carries two maps of the system.
The gap between these maps is complexity debt. It grows when systems evolve without explanation. Humans start to confuse legacy with design. AI cannot tell accident from intent. Understanding becomes the bottleneck.
Ward Cunningham’s technical debt metaphor fits neatly here. Debt is not sin. It is a choice with a cost. The cost rises when the map of intent and the map of reality drift apart.
Evolution without documentation
Most drift is not malicious. Products grow. Teams patch, extend, and improvise under time pressure. The breadcrumbs get lost.
Over time, no one can state which quirks were strategic and which were survival tactics. To rediscover intent, people become archaeologists, digging through commit history, Slack threads, and dashboards. AI does the same, only faster and with fewer priors.
This is where standards matter. ISO 42010 treats architecture description as part of the system of control, not paperwork. It asks us to make decisions, rationales, views, and stakeholders explicit. In plain language, it is a reminder that if we do not write down the why, we will pay to relearn it later.
Recommended by LinkedIn
The human factor: complexity in conversation
Complexity is technical and social. Humans are not naturally transparent. We summarise to be kind, we omit to be fast, we limit to be safe. You only find the right question after you already understand part of the answer.
Conway’s Law tells us that system shape mirrors communication patterns. If information travels slowly or selectively, design will reflect that. Architectural opacity is often a social opacity with a nicer interface.
AI will be no different. A model can retrieve and correlate, but it still depends on what we make legible. It cannot ask the perfect follow up until it has enough context to know something is missing. It inherits our blind spots and presents them confidently.
Documentation is back in fashion
Documentation is not admin. It is architecture.
We used to document for auditors. Then for maintainers. Now we document for intelligence systems, human and artificial. Writing things down is how we align intention and reality. It is how we give AI access to the why, not just the what. It is how we turn folklore into evidence.
ISO 42010 is dry for a reason. It gives us a shared way to describe decisions, trade offs, and views so that people and machines can reason about them. In practice, lightweight patterns work best. Architecture Decision Records keep choices and consequences close to the code. Diagrams with viewpoints keep context close to the audience. Tests make behaviour explicit where prose can go stale.
A simple operating model for alignment
Keep both humans and AI on the same map with a short loop.
Declare intent. Capture principles, ADRs, and guardrails where they are searchable. Observe reality. Instrument behaviour through telemetry, usage, incidents, and support signals. Infer evolution. Use humans and AI to detect drift between intent and behaviour. Decide disposition.
This is not bureaucracy. It is hygiene. It is how an organisation stays legible as it scales.
Leadership’s job: make complexity visible
Leaders cannot remove complexity by messaging. They can decide where it should live and how it is understood. The smartest teams do not pretend complexity is gone. They surface it, document it, and design so others can build safely on top. Complexity can be moved, removed, or made visible. The art is knowing which you are doing, and proving it.
References
Reflection
Where does complexity hide in your organisation? Is it buried in the code, the culture, or the conversations? What would it take to make the why legible to both your people and your machines?
#Leadership #SoftwareEngineering #AI #Documentation #Complexity
I read a book called The Collapse of Chaos once, highly recommend it. It was all about the relationship between simplicity and complexity: how simplicity can surface out of complex systems and complexity can arise from simple foundations. They called it "simplexity", the relationship between the two.