Skip to content
Merlon Docs

Documentation and software reliability

Why Merlon Docs exists: the link between documentation quality and the cost of unreliable software, stated no more strongly than the sources allow. Its parent is Vision and roadmap. Public copy that cites these figures follows Benefit claims and evidence.

The scale of the problem

Section titled “The scale of the problem”

Software failures are expensive, and the published estimates run from hundreds of billions to trillions of US dollars a year.

Source Scope Figure
CISQ, Cost of Poor Software Quality 2022 United States, 2022 $2.41 trillion in total, about $1.8 trillion of it from operational failures
Splunk and Oxford Economics, downtime study Forbes Global 2000, 2024 $400 billion a year in downtime
Siemens, The True Cost of Downtime 2024 Fortune Global 500 industrials About $1.4 trillion a year in unplanned downtime

All three are industry studies, and each sponsor sells tools for the problem it measures. Read them as orders of magnitude, not precise totals. Even cut by a factor of ten, each figure stays in the tens of billions of dollars a year or more.

Documentation is one cause among several

Section titled “Documentation is one cause among several”

The CISQ report doesn’t identify one root cause. Its own focus areas are security vulnerabilities, weaknesses in the software supply chain, and technical debt. Missing or stale documentation sits beside those causes:

  • Requirements and intent. A decision made in a ticket or a pull request and never written down. The next change can undo it.
  • People. Knowledge that lives in one person’s head and leaves with them.
  • Process. Reviews that can’t check intent, because the intent isn’t recorded anywhere a reviewer reads.

Merlon Docs addresses the documentation cause only. It doesn’t fix vulnerabilities, supply chains, or technical debt.

Why documentation quality matters

Section titled “Why documentation quality matters”

DORA’s research doesn’t claim documentation caused these costs. It finds that documentation quality drives adoption of technical practices and amplifies their effect on organizational performance.

  • With high-quality documentation, the same technical capabilities deliver about 1.2 to 12.8 times more impact on organizational performance (DORA 2023).
  • Teams with higher documentation quality are 2.4 times more likely to report better software delivery and operational performance (DORA 2021).
  • The DORA AI Capabilities Model lists AI-accessible internal data and healthy data ecosystems among the practices that multiply the effect of AI adoption.

DORA 2022 and 2023 didn’t find a direct effect of documentation quality on software delivery performance alone. The effect is amplification of other capabilities, not a throughput dial.

Where Merlon Docs fits

Section titled “Where Merlon Docs fits”

There’s no substitute for knowing the system. When a project leaves its intent, features, and operating knowledge unwritten, from the technical parts to the non-technical ones, teams ship software with gaps that someone later pays for.

Merlon Docs is a keystone AI skill for that one cause. It gives the knowledge a place to live that people and agents both read, in small shards that change in the same pull request as the code. merlon check keeps the structure intact. Whether the words are true still depends on the agent following the skill and on human review. See Usage model for the workflow.

Section titled “Related”