Soundtrack for this blog: Pink Floyd, Time
I still remember a system I inherited about ten years into my career. It was not a crisis, just a quiet handover. The previous team had done what most responsible teams try to do: they left documentation behind. Architecture diagrams, operating procedures, onboarding notes. Everything looked complete. Almost comforting.
But as I started working with the system, something felt off. The documentation told me what existed, but not why. Certain constraints made no sense. Some design choices seemed inefficient, even careless. Yet the system was stable, and it had clearly survived years of production use.
The missing piece wasn’t documentation. It was intent. That experience reminded me of something The Effective Executive by Peter Drucker articulates with unsettling clarity:
“What gets measured gets managed.”
Over time, I’ve learned to add an unspoken second sentence to that quote: but what gets documented determines whether anyone understands it later.
Documentation Is an Act of Translation
Good documentation is not a record of activity. It is a translation of thinking.
This idea aligns closely with The Fifth Discipline, where Peter Senge describes learning organizations as those that make mental models explicit. Documentation, at its best, does exactly that. It exposes assumptions. It freezes reasoning long enough for someone else to examine it.
When documentation fails, it is rarely because it is incomplete. It fails because it answers the wrong question. Instead of explaining why the system is the way it is, it catalogs what currently exists. That distinction matters more than most teams realize.
I’ve seen teams obsessively update diagrams to reflect every deployment change, while never recording the original trade-offs that shaped the system. The result is documentation that is technically accurate and practically useless.
Evidence Ages Differently Than Understanding
Evidence behaves differently.
Logs, tickets, approvals, and metrics are invaluable — but they age poorly when divorced from context. A change record from three years ago may prove that something happened, but it rarely explains whether it was a good idea.
This echoes a warning from Thinking in Systems, where Donella Meadows reminds us that events are the least informative level of understanding a system. Events show what happened, not why it keeps happening.
In one organization I worked with, incident reports were immaculate. Timelines were precise. Actions were logged. Yet the same class of incident kept recurring. The evidence was flawless. The documentation of system behavior and constraints was not.
They were collecting proof, not insight.
The Dangerous Middle Ground
The most fragile organizations I’ve encountered are not the ones with poor documentation or weak evidence. They are the ones that blur the two.
Documentation starts being written after incidents to justify outcomes. Evidence is cherry-picked to align with policies that were never operationalized. Over time, documents stop serving engineers and start serving defenses. This is precisely the failure mode described in Normal Accidents, where Charles Perrow shows how complex systems drift toward failure not through negligence, but through layers of well-intentioned process that obscure reality.
When documentation becomes a proxy for control, organizations lose their ability to see themselves clearly.
A Practical Rule I Learned the Hard Way
After many handovers, audits, and post-mortems, I’ve adopted a simple rule that I now teach teams explicitly:
If removing something makes the system harder to understand, it is documentation.
If removing something makes the system harder to trust, it is evidence.
They are complementary, not interchangeable.
This framing consistently unlocks better conversations. Teams stop arguing about “missing documentation” when what they really mean is “missing evidence.” Auditors stop demanding process descriptions when what they actually need is execution proof. Engineers stop resenting documentation when it is clearly about preserving intent rather than defending compliance.
Why This Matters Long After the Project Ends
Most systems outlive their creators.
Most documentation does not.
That gap is where operational risk quietly accumulates.
As Managing the Unexpected argues, resilient organizations are not those with the most controls, but those with the best shared understanding of how their systems behave under stress. Documentation is how that understanding survives turnover. Evidence is how it remains credible.
One without the other is either naïve or blind.
The GreenMethod Perspective
At GreenMethod, we are deliberate about this separation.
We document structure, intent, boundaries, and rationale — the things that should remain stable even as systems evolve. We rely on evidence to demonstrate execution, accountability, and behavior over time. We do not try to collapse one into the other.
This is not about producing more artefacts. It is about producing artefacts that age well.
Over the years, I’ve noticed something reassuring: organizations that respect this boundary tend to experience calmer audits, cleaner handovers, and more productive incident reviews. Not because they are perfect, but because they are legible — to themselves and to others.
The organizations that endure are not the ones with the thickest binders or the most dashboards. They are the ones that understand what each artefact is for. Documentation explains. Evidence proves. And experience teaches you that confusing the two is far more costly than investing properly in both.