Organizations treat documentation as if it were the anchor of truth in their infrastructure.
It promises structure, continuity, onboarding, governance and transparency.

But documentation rarely fulfills that promise.
Not because people are lazy, but because the system it tries to describe — and the organization around it — move faster than any document can keep up with.

This article explores why documentation consistently fails to represent technical truth, why this is not a problem you can fix with discipline, and why the illusion persists nonetheless.

1. Documentation Should Describe What Is True — But Usually Doesn’t Link to heading

Documentation ought to describe the state of the system as it is at the time of writing.

That means writing in a factual, verifiable present tense:

“This system behaves like this.”
“This component currently works like this.”
“This process produces these outcomes.”

But most documentation is written in a hypothetical or future-oriented style:

“The system will…”
“This component is intended to…”
“This process should…”
“The architecture ensures that…”

It describes expectations and desired behaviour, not how the system actually behaves.

The moment you recognize this mismatch, the illusion becomes obvious:

Documentation uses the grammar of truth,
but expresses the content of intention.

2. Documentation Reflects Intent, Not Behaviour Link to heading

Documentation usually represents:

the design people intended
the processes people hope to follow
the assumptions teams make
the constraints they believe exist
the behaviour they expect to see

It almost never represents:

effective configuration
inherited defaults
runtime overrides
unplanned workarounds
silent changes in dependencies
updates in external systems
drift caused by human interaction
cross-team decisions

This is why you almost never hear:
“Read the documentation first — it explains everything.”

Instead you hear:
“Ask person X. She knows how it actually works.”

That single sentence reveals everything about the illusion.

3. Organizational Drift Outpaces Technical Drift Link to heading

Technical drift is bad enough:

hotfixes
small config edits
new defaults
patch-level behaviour changes
different machine histories

But organizational drift is often stronger:

teams are reorganized
responsibilities shift
priorities change
new management arrives
cross-team boundaries move
specialists leave
ownership becomes unclear

Documentation tries to describe a system with a moving target and a moving observer.

It cannot keep up.

Documentation is rarely created because engineers need it.
It is mostly created because organizations demand it:

auditors require it
managers expect it
compliance mandates it
onboarding frameworks mention it
process governance depends on it

Its primary function is not operational clarity, but organizational signalling:

“This system is under control.”
“This environment is structured.”
“This process is documented.”
“This team is compliant.”

But this signalling is fragile.
It maintains an appearance of understanding without guaranteeing actual understanding.

Documentation is enforced, not natural.
And enforced artifacts decay first.

4.1 Documentation Follows the Author’s Mental Model Link to heading

Documentation does not represent the system.
It represents the author’s worldview.

A technically-minded engineer writes:

dense
precise
implementation-focused
system-first

A process-oriented person writes documentation very differently:

process-focused
abstract
role-driven
using a different vocabulary and mental model

Both produce “documentation”.
Both mean completely different things.

This mismatch alone prevents documentation from forming a coherent truth-layer.

4.2 Documentation Depends on External Teams — and Cannot Detect Their Changes Link to heading

Most systems span multiple teams.
Documentation references:

firewall rules
identity providers
app behaviours
network paths
platform defaults
CI/CD policies
shared components
external APIs

But documentation cannot detect when those teams change something.

If team A updates a subsystem, team B’s documentation silently becomes wrong.

Cross-team coupling makes documentation decay faster than any single team can compensate for.

4.3 Documentation Can Be Valuable — But Only Locally Link to heading

There is a type of documentation that is genuinely useful:
documentation created by a person or a small team to deeply understand a specific process, to reproduce complex steps, or to ensure that a particular workflow can be repeated reliably.

This kind of documentation is practical, task-oriented and close to the actual work.
It helps individuals regain context, avoid mistakes and stabilize routines.

But this usefulness does not scale to organizational documentation.
Local documentation describes what one team does.
Organizational documentation tries to describe how the entire system behaves — and that is where the illusion reappears.

5. Documentation Is Not the Knowledge Graph We Think It Is Link to heading

Documentation does not contain:

effective configuration
real dependency graphs
inheritance paths
runtime defaults
drift history
correlation patterns
operational shortcuts
exception cases
tribal knowledge

The real knowledge graph lives in:

telemetry
runtime configuration
call traces
incident logs
senior engineers
outdated conventions
undocumented standards
people’s memory and judgement

Documentation captures the narrative.
Systems capture the truth.

6. Why Documentation Cannot Stay Up to Date Link to heading

Several structural forces make this unavoidable:

6.1 Complexity Outpaces Idea Capture Link to heading

Systems evolve faster than humans can write.

6.2 The Cost of Maintenance Is Invisible Link to heading

Nobody budgets time for documentation upkeep.

6.3 Documentation and Tests Die First Under Pressure Link to heading

When delivery pressure increases:

tests degrade
documentation decays

Both look “optional” in the moment.
Both are foundational in hindsight.

6.4 No Single Person Understands the Whole System Link to heading

Documentation becomes fragmented across perspectives.

6.5 Documentation Does Not Self-Validate Link to heading

Config APIs error when wrong.
Documentation never does.

6.6 People Trust People More Than Documents Link to heading

If documentation conflicts with an experienced engineer,
everyone trusts the engineer — correctly.

Documentation is optional truth.
Runtime behaviour is mandatory truth.

7. Ways to Address the Problem Link to heading

Documentation cannot become perfect.
But it can become honest, maintainable and useful.

7.1 Document Intent Explicitly — Not Behaviour Link to heading

Write: “Intended behaviour”,
not
“Actual behaviour”.

Be precise about what the document is and what it is not.

7.2 Pair Narrative With Telemetry Link to heading

Documentation should exist next to:

effective config
runtime state
dependency graphs
drift snapshots

Narrative + data is stronger than narrative alone.

7.3 Automate All Factual Documentation Link to heading

Humans should explain context.
Tools should capture facts.

Automate:

version inventories
config extractions
dependency maps
drift diffs
change histories

7.4 Keep Docs High-Level Link to heading

Deep details decay immediately.
High-level docs remain stable and useful.

7.5 Accept Documentation as Guidance, Not Truth Link to heading

Its purpose is orientation, not representation.

The truth must come from the system’s behaviour.

Closing Link to heading

Documentation is valuable — but not in the way organizations expect it to be.

It is not a mirror of technical truth.
It is not a guarantee of understanding.
It does not prevent drift.
It does not replace telemetry.
It cannot keep up with the pace of change.

Documentation tells a story about a system.
Telemetry tells the truth.

The illusion breaks the moment we acknowledge this.
And that is where real understanding begins.

Follow-Up Questions Link to heading

Should documentation describe intent, behaviour, or both — and how do we separate them clearly?
How can telemetry-based systems provide “living documentation” automatically?
What is the minimal useful level of documentation for onboarding?
How can we detect when documentation has drifted away from reality?
Would documentation become more honest if it stated explicitly what parts are assumptions?

Get in touch

Email me: starttalking@sh-soft.de