Imagine an NFL team reaching the fourth quarter of a close game and losing its starting quarterback to injury.
The backup has to step in immediately.
He does not walk onto the field and start reverse-engineering the offense. He does not ask the wide receivers where they usually run, guess which protection the offensive line expects, or try to reconstruct the team's red-zone strategy from the previous three quarters.
He has the playbook.
The routes, formations, protections, responsibilities and adjustments have already been captured and practiced. The backup still needs skill and judgment, but he is not being asked to rediscover how the entire system works before he can operate inside it.
Now imagine the opposite.
The team's offensive knowledge exists mainly in the starting quarterback's memory. Some plays are written down, others were changed informally during practice, and several important adjustments are understood only by the coaches who introduced them.
The backup may still be talented, but replacing one person has suddenly become much more expensive and much more risky.
Long-lived software applications develop exactly this problem.
Years after launch, a developer may be asked to fix a billing rule, modify an integration or investigate a production failure in code they did not originally write. Before touching it safely, they need to understand how that part of the system fits into everything around it: which services depend on it, how data moves through the workflow, why certain decisions were made, what assumptions must remain true and how the change reaches production.
When that knowledge is documented, the engineer can begin from the team's existing understanding.
When it is not, the organization pays them to reconstruct it.
And it can pay for that same reconstruction repeatedly: when another developer joins, when a production incident occurs, when responsibility moves to another team, or when the people who originally built the application leave.
That is the economic value of good documentation.
Good documentation makes an application cheaper to maintain because it preserves the knowledge engineers need to understand, troubleshoot and change the software without repeatedly rediscovering how the system works.
DORA's research on documentation quality reinforces that documentation is not simply administrative overhead. Clear, reliable and easy-to-find internal documentation supports better knowledge sharing and stronger software-delivery and operational performance.
For Levelworks, this is the practical purpose of Well Documented App Health. The objective is not to create a larger wiki. It is to ensure that important application knowledge remains available when the next person needs to make a safe change—whether or not the person who originally understood it is still on the field.
Consider what happens when an engineer receives what appears to be a small maintenance task:
Update the customer-export process so archived accounts are excluded.
Before changing the query, they may need to determine:
None of those activities directly implements the requested change.
They are the cost of becoming sufficiently informed to make it safely.
On a well-documented application, much of that information may be available within minutes.
On a poorly documented one, the engineer begins software archaeology.
This is why two codebases of similar technical complexity can have very different maintenance costs. The expensive application is often the one where every maintenance task begins with a discovery project.
Most long-lived applications accumulate experts.
Someone knows the billing system.
Someone else knows the strange authentication integration.
Another engineer remembers why customer records cannot be deleted directly.
Expertise itself is valuable. The problem arises when the system is understandable only through those individuals.
Then routine maintenance becomes dependent on availability:
“Ask Rohan before changing that.”
“Only Maria knows how production deployment works.”
“We should wait until James is back because he built the integration.”
This is often called tribal knowledge: useful operational or technical knowledge held by particular people rather than made available to the wider team.
The cost appears in several forms.
Work waits for specialists. Specialists are interrupted repeatedly because everyone needs their context. New engineers take longer to become independent, and when experienced people change roles or leave, knowledge disappears with them.
DORA's research describes quality internal documentation as a mechanism for sharing and scaling knowledge across teams. Its current guidance also emphasizes that high-performing teams treat documentation as part of software delivery rather than an optional administrative activity. DORA: How documentation supports productive software teams
Documentation does not eliminate expertise.
It makes expertise transferable.
Imagine two engineers joining different maintenance teams.
The first receives:
The second receives a repository URL and a message saying:
“Clone it and ask if you get stuck.”
Both engineers may eventually become productive.
The second one will consume far more existing-team time while getting there.
Every missing instruction becomes a conversation:
Which runtime version?
Which database?
Where do local credentials come from?
Which service needs to start first?
What test data is safe to use?
Where is the staging environment?
Good documentation converts many of those interruptions into self-service learning.
GitHub's own repository guidance recommends using a README to explain what a project does, how people get started, where they can get help and who maintains it. GitHub: About README files
A good repository README does not need to explain the entire application.
It should remove the first set of unnecessary questions.
That saves time every time somebody joins, returns to an unfamiliar repository or temporarily helps another team.
A codebase tells you what the software currently does.
It is much less reliable at telling you how the system fits together at a useful level or why certain boundaries exist.
Suppose an application contains:
An engineer fixing a report-generation bug does not initially need every class and function.
They need a map.
Which component creates the job?
Where does the data come from?
Which queue is involved?
Where is the generated report stored?
What external systems participate?
A small number of maintained architecture diagrams can reduce the time required to form that mental model.
The C4 model, created by Simon Brown, uses different levels of abstraction—such as system context and container diagrams—to communicate software architecture without requiring every diagram to descend into code-level detail. Its guidance notes that context and container diagrams are sufficient for many software teams. C4 Model: Architecture diagrams
That is an important documentation principle.
Document at the level required to answer maintenance questions.
A 700-box diagram generated automatically from every class may be technically complete and practically useless.
One of the most expensive maintenance questions is:
“Why was it built this way?”
The implementation may clearly show that invoices are processed asynchronously.
It may not explain why.
Perhaps the original synchronous approach repeatedly exceeded a payment-provider timeout. Maybe an audit requirement means records must be retained for seven years. Perhaps a database table that looks redundant exists because an external integration relies on its identifiers.
Without that context, a future maintainer may “simplify” something that was deliberately designed around a constraint.
This is where Architecture Decision Records (ADRs) are particularly useful.
Martin Fowler describes an ADR as a short document recording an important decision along with its context, rationale and consequences. He emphasizes their usefulness months or years later, when maintainers need to understand why a system is structured the way it is. Martin Fowler: Architecture Decision Record
A useful ADR might explain:
Decision: Process payment callbacks asynchronously.
Context: Provider callback response must return quickly; previous synchronous processing caused retries.
Consequence: Event ordering and idempotency must be preserved.
That is far more useful than 15 pages describing the payment worker's classes.
The code tells the maintainer how asynchronous processing happens.
The ADR tells them why changing it casually could be dangerous.
Documentation becomes particularly valuable when time pressure is high.
During an incident, responders are often trying to answer practical questions immediately:
This is the role of operational runbooks and playbooks.
Google's Site Reliability Engineering guidance reports that thinking through and recording emergency procedures in a playbook produced roughly a threefold improvement in mean time to repair compared with improvising the response in the experience described by its SRE organization. Google SRE: Emergency response and playbooks
The point is not that every incident can be reduced to a checklist.
Google explicitly notes that playbooks do not replace engineers who can reason through unexpected failures.
Their value is that responders do not waste the first twenty minutes rediscovering routine steps during a high-pressure situation.
Google Cloud's operational guidance similarly recommends documenting incident procedures in runbooks that cover triage, investigation, resolution, communication, tools and relevant contacts—and keeping those runbooks current. Google Cloud: Manage incidents and problems
[Internal Link: “Application Incident Response: What Should Happen When Your App Goes Down?”]
Maintenance includes many tasks that occur repeatedly:
If the procedure exists only in someone's memory, each occurrence carries unnecessary uncertainty.
A concise runbook can capture:
Trigger: When should this procedure be used?
Preconditions: What needs to be checked first?
Steps: What should be done, and in what order?
Verification: How do we know it worked?
Rollback: What should happen if it fails?
Escalation: Who needs to become involved if the normal procedure does not work?
Once the process is stable, documentation can also reveal opportunities for automation. A well-understood five-step manual runbook is easier to automate safely than a process no one can describe consistently.
Imagine an API request begins taking eight seconds.
The logs show that most of the time is being spent waiting for another service called CustomerEligibility.
What is that service?
Who owns it?
Which dashboard monitors it?
Does it call another provider?
Is there a timeout or circuit breaker?
Without documentation, diagnosis keeps branching.
Every unanswered architectural question creates another investigation.
Good operational documentation can provide:
It does not need to reproduce everything visible in monitoring or source code. It should connect maintainers to the right evidence quickly.
That distinction matters because useful documentation is often more about navigation than exhaustive explanation.
One of the most expensive moments in an application's life can occur when responsibility changes hands.
An internal team may transfer maintenance to another department. A startup may replace its original development agency, or a company may bring outsourced development in-house.
If documentation is weak, the incoming team has to reverse-engineer the application before it can confidently maintain it.
The source code alone rarely answers questions such as:
Every missing answer increases transition time and creates risk.
A well-documented application can never make a handover instantaneous, but it allows knowledge transfer to start from an existing system of record rather than a blank page.
[Internal Link: “The Application Handover Checklist: What Documentation Should Your Development Team Provide?”]
Suppose an engineer spends four hours discovering why a scheduled task occasionally duplicates records.
They eventually learn that two schedulers overlap during a particular failover condition.
The issue is corrected.
Six months later, another engineer sees unusual scheduler configuration and wonders why it exists.
If the reasoning was never recorded, the organization pays again to rediscover it.
This happens constantly in mature applications.
Teams repeatedly investigate:
Documentation converts the first investigation into reusable organizational knowledge.
A short note can preserve hours of reasoning.
This is also why post-incident documentation matters. Google's SRE guidance stresses maintaining a history of failures so future engineers can learn from what previously broke instead of repeating the same discovery process. Google SRE: Emergency Response
Documentation therefore creates value repeatedly, not only when it is written.
Documentation has its own maintenance cost.
A team can easily create hundreds of pages that nobody uses.
The wrong objective is:
“Document everything.”
That produces duplicated, outdated material and eventually makes reliable information harder to find.
DORA defines quality documentation through characteristics such as clarity, findability and reliability, not document volume. Its current guidance also explicitly says documentation needs to be actively created and maintained. DORA: Documentation Quality
Google Cloud's Well-Architected Framework makes a similar point: documentation quality comes from clarity, usefulness and being maintained as the architecture changes, rather than from producing a particular quantity of material. Google Cloud Well-Architected Framework
The cheapest documentation is not the shortest.
It is the smallest amount that reliably answers the maintenance questions people repeatedly need answered.
Different applications require different levels of detail, but maintenance teams generally benefit from a small set of documentation categories.
Documentation
Maintenance question it answers
Application overview
What does this system do and where do I start?
Architecture map
What are the major components and dependencies?
Setup instructions
How can I run and test it?
Architecture decisions
Why is the system built this way?
Deployment guide
How does a change reach an environment?
Operational runbooks
How do we perform recurring or emergency procedures?
Integration documentation
Which external systems do we depend on and how?
Data notes
Where does important data live and what constraints apply?
Ownership information
Who is responsible for each area?
Known constraints
What should a maintainer be particularly careful about?
Not every application needs a large documentation portal.
A small system may need a strong README, one architecture diagram, several runbooks and a handful of ADRs.
A large distributed platform will naturally need more.
The appropriate amount follows the cost of misunderstanding.
Documentation becomes unreliable when code changes in one place and related documentation lives somewhere nobody remembers to update.
Where practical, keep technical documentation close to the code or configuration it describes.
GitHub recommends README files for project-level information and allows repository documentation to evolve alongside source history. GitHub: About README files
ADRs are also commonly stored with the application repository because architectural decisions can then move through the same version-control and review process as the software.
This creates a useful maintenance habit:
A change is not complete if it makes an important document wrong.
For example:
Documentation maintenance then becomes part of application maintenance rather than a cleanup project scheduled every two years.
Every important document should have an implied or explicit answer to two questions:
Who keeps this current?
When should somebody use it?
Documents without ownership decay.
Documents without a clear audience become dumping grounds.
A runbook belongs to the team responsible for the service.
A repository README should evolve with the repository.
An architecture overview should be reviewed when the system structure changes.
Ownership can also be represented through repository mechanisms. GitHub's CODEOWNERS feature, for example, allows teams to identify responsibility for files and automatically involve relevant owners in changes. GitHub: About CODEOWNERS
The broader principle is simple: documentation should have a maintenance path of its own.
Outdated documentation can cost more than missing documentation.
If no deployment guide exists, an engineer knows they need to investigate.
If a deployment guide confidently describes a process that stopped being correct eighteen months ago, the engineer may follow it.
Maintenance teams should therefore remove or clearly archive:
ADRs provide a useful model here: instead of rewriting history when a decision changes, a record can be marked as superseded and linked to the replacement. That preserves useful historical context without implying that the old decision is still current. Martin Fowler: Architecture Decision Record
Trust is one of documentation's most valuable properties.
Once maintainers repeatedly discover that documents are wrong, they stop using them—even when other documents remain accurate.
A useful way to decide what needs documenting is to imagine a capable engineer joining tomorrow with no historical context.
Could they answer:
You do not need a 200-page manual to answer those questions.
Often a navigable set of short documents is better.
A repository README can lead to architecture documentation. The architecture page can link to integrations. Services can link to their runbooks. ADRs can explain unusual decisions.
Think of documentation as a map through the application rather than an encyclopedia about it.
Page count is a poor documentation metric.
So is counting how many documents were created this quarter.
Better signals include whether developers can find reliable answers to recurring maintenance questions.
Watch for patterns such as:
These are documentation failures expressed as engineering cost.
DORA's research is useful here because it measures documentation quality through attributes such as whether documentation helps people accomplish goals, is accurate, is easy to find and is organized clearly. DORA 2021 State of DevOps Report
The practical test is not whether documentation exists.
It is whether maintainers can use it to do real work.
A common objection is:
“The code should be self-documenting.”
Well-written code absolutely reduces the amount of explanation required.
Clear naming, coherent modules and useful tests make maintenance easier.
They still cannot capture every piece of context surrounding an application.
Source code does not necessarily explain:
Good documentation fills the gaps that code is poorly suited to fill.
That prevents another common mistake: adding huge comments that merely translate obvious code into English.
Document what future maintainers cannot easily infer.
Applications can remain in production for ten or fifteen years.
People rarely remain in exactly the same roles for that long.
Teams reorganize. Vendors change. Developers leave, managers move, infrastructure is replaced and products acquire features nobody imagined when the first architecture diagram was created.
If application knowledge lives primarily in human memory, the organization's understanding of its own system decays every time one of those transitions occurs.
Documentation gives that knowledge a longer lifetime.
This is why Well Documented is a distinct Levelworks App Health aspect. It supports Explainable & Debuggable because maintainers can understand the system and its decisions; Supported because operational knowledge can be shared; and Seamlessly Updatable because changes are safer when dependencies and procedures are known.
[Internal Link: “How Git Makes Application Maintenance Safer”]
Documentation always has a cost.
Someone has to write the architecture overview, update the deployment instructions, record the design decision or improve the runbook after an incident.
The alternative is not free.
The alternative is paying engineers later to reconstruct the same information under worse conditions.
You pay when a new maintainer spends three days understanding a service that could have been explained in an hour.
You pay when an incident responder searches through old messages for a recovery command.
You pay when a team repeats an architectural investigation because the original reasoning disappeared with the people who made the decision.
You pay when a supposedly straightforward handover turns into months of reverse engineering.
You pay again when outdated knowledge causes a change to break something nobody knew depended on it.
Good documentation changes where that time is spent.
Instead of repeatedly buying the same understanding through investigation, the team captures the knowledge once, keeps the parts that continue to matter current, and reuses them every time the application needs to change.
That is the economics of documentation in maintenance: a relatively small investment in preserving understanding prevents the organization from continually paying to rediscover its own software.
