Duplicated knowledge is the real problem behind software documentation

Lately I have been thinking a lot about software documentation, partly because I have been taking classes on Information and Knowledge Management in software engineering. The more I think about it, the more I come back to an idea that has bothered me for years: duplication of knowledge.

When developers hear DRY, most of them think of duplicated lines of code. But the original definition, from The Pragmatic Programmer, is much broader than that:

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

The real problem is not duplicated code. It is duplicated knowledge. The same rule, decision, or behavior gets represented in several places, often in different formats, maintained by different people, and updated at different times. Once that happens, divergence is almost inevitable.

This is the same concern behind the idea of a single source of truth, and it is closely related to orthogonality: when knowledge is duplicated, one conceptual change requires updates to many different artifacts. I find it a useful lens not only for code, but for software engineering as a whole. Let me start with a few places where this duplication shows up, and then get to how AI is changing the picture.

Documentation is a second copy of the code

Documentation is probably the clearest example. A large part of it describes knowledge that already lives in the code: behavior, rules, flows, contracts, and constraints. The same knowledge ends up written twice, once in natural language and once in a programming language, and only one of them actually runs. It is not hard to guess which one stays up to date.

That is the root of the most common complaint about documentation: it gets outdated. Docs fall behind, people stop trusting them, and eventually everyone goes straight to the code to see how the system really behaves. In many organizations, the consequence goes even further. If the docs cannot be trusted, why write them at all?

I have seen large startups and enterprises with little to no meaningful documentation, relying almost entirely on tacit knowledge, the kind that lives inside people's heads. That works while the team is stable. It stops working when people move to other projects or leave the company. At that point, the organization does not just lose documentation. It loses memory.

Diagrams are copies too

Architecture diagrams are useful, but manually maintained ones have exactly the same problem as written docs: they are another copy of knowledge that lives somewhere else. The moment a service is renamed, split, or retired, the diagram is wrong, and nothing tells you so.

Ideally, diagrams should be generated from real sources of truth, such as source code, infrastructure as code, deployment definitions, or cloud metadata, instead of being drawn by hand and depending on someone remembering to update them.

Code comments as duplicated knowledge

Duplication also happens inside the code itself. Comments have an important place in software, but mainly when the code is genuinely hard to follow, when the intent is not obvious, or when an important trade-off needs to be preserved for future readers. A comment on code that already explains itself is just another copy.

This kind of comment adds almost no value:

// Increment the counter
counter++;
 
// Check if the user is active
if (user.isActive) {
  sendEmail(user);
}

These comments are correct, but they only restate what the code says. And the first time someone changes the code without touching the comment, they become wrong.

Now compare that with a case where the code is less obvious for a good reason:

// We intentionally retry only on 429 and 5xx responses.
// Retrying all failures caused duplicate charges in the past because some partner
// endpoints complete the operation but time out before sending the response.
// Do not broaden this retry policy unless the downstream API is proven idempotent.
async function capturePayment(request: CapturePaymentRequest) {
  return retry(async () => paymentProvider.capture(request), {
    maxAttempts: 3,
    shouldRetry: (error) =>
      error.status === 429 || (error.status >= 500 && error.status < 600),
  });
}

This comment does not describe what the code does; anyone can read that. It preserves what the code cannot express: a production incident, a business risk, and a warning for the next person who feels like "simplifying" the retry policy.

Beyond documentation and code

Duplication of knowledge is not limited to docs, diagrams, and comments. It shows up in backlogs, tickets, acceptance criteria, wikis, runbooks, and even in the way different teams describe the same requirement in different words. Whenever the same rule is expressed in several places, we create maintenance overhead and raise the chance of divergence.

That does not mean every repeated representation is wrong. A test, for example, restates a business rule on purpose, and that is exactly what makes it useful. The difference is that a test is checked against the code on every build, while a wiki page is not. Duplication is tolerable when something keeps the copies honest. Without that, it is just a matter of time before they disagree.

How AI is changing documentation

For a long time, organizations have tried to solve the documentation problem with wikis, intranets, knowledge bases, internal portals, shared folders, and all kinds of documentation processes. These tools still have value, but I suspect many of them were compensating for the deeper issue. If documentation mirrors the code, it is by definition a second representation of the same knowledge, and duplicated knowledge drifts.

This is where AI changes things. Using AI to read code, explain systems, and answer questions about a repository is already part of everyday engineering work. What I find interesting is not that AI can help us write documentation. It is that AI may remove the need to keep a large part of it.

Instead of maintaining pages that restate the source code, we can ask directly: how does this module work? Which business rules does this workflow implement? What does the architecture of this service look like? The answer is generated from the actual source of truth at the moment we need it, so it cannot fall out of date the way a stored document does.

This also helps with one of the hardest organizational problems: knowledge loss. When the most experienced developer leaves a team, AI can still help everyone else understand what the system does by reading the code, tests, configs, and schemas.

There are limits, of course. An AI explanation is only as good as what it reads, and it can be confidently wrong, so it is a starting point to verify, not an oracle. And documentation written for people outside the codebase, like a public API reference or a user guide, is a product in its own right, not a mirror of the code.

AI can also make duplication worse. Now that agents write a significant part of the code in many teams, the redundant kind of comment has become more common. Coding agents often add comments that are technically correct but unnecessary, simply because the pattern is everywhere in the code they learned from. That is why I think it is worth being explicit in the instructions we give them, for example in an AGENTS.md or CLAUDE.md file:

Only add comments when the code is not easy to read, when the intent is not
obvious, or when an important trade-off needs to be preserved. Never restate
what the code already says.

What should still be written down

The most important limit is that behavior is not the same as intent. AI can recover what a system does. It cannot recover why it was built that way: the trade-offs, the alternatives that were rejected, the business context, and the constraints, political ones included, that shaped the code over time. None of that is in the code, so no amount of reading the code will bring it back.

So my view is not that AI will eliminate documentation. It is that AI is replacing documentation's traditional role as a persistent mirror of system behavior, and that is probably a good thing. The effort we used to spend restating what the code already says can go into what the code cannot say: intent, trade-offs, architectural decisions, business context, and historical reasoning.

Architecture Decision Records (ADRs) are a good example of this kind of documentation. They capture a decision and its reasoning at the moment it is made, and they do not go stale the way behavioral docs do. A decision made in 2024 is still a decision made in 2024, even after a newer one replaces it.

Duplication is getting cheaper, but it is not free

There is another side to this that I have been thinking about recently. AI does not only change how we read knowledge. It also changes how we maintain it. When an agent changes the code, it can update the README, the API reference, and the diagram source in the same pull request. Keeping copies in sync used to depend on someone remembering to do it. Now it can be one more line in the agent's instructions. In that sense, duplication of knowledge is becoming much cheaper.

Cheaper, but not free, for two reasons.

The first is that the work still has a cost. Every copy is something an agent has to find, read, and update on every relevant change, and that means tokens, time, and money, plus a bigger diff for someone to review. Each piece of knowledge we avoid duplicating is synchronization work we never have to pay for, whether a human or an agent does it.

The second is context. An agent can only keep in sync what it can see. A README in the same repository is easy. A Confluence page, a ticket with acceptance criteria, an onboarding deck, or an integration guide in another team's repository usually is not. Those copies drift exactly as they always did, except now it is easier to assume they are being taken care of.

So AI lowers the price of duplication without removing it. The copy that is cheapest to keep in sync is still the one that does not exist.

Less redundant documentation

In software engineering, we talk a lot about avoiding duplicated code. Maybe we should talk more about avoiding duplicated knowledge. Outdated documentation, stale diagrams, useless comments, and inconsistent backlogs may all be symptoms of the same issue: we keep creating parallel representations of the same truth, and then we are surprised when they stop matching.

That is why I do not think the future is no documentation. It is far less redundant documentation: less effort maintaining second copies of knowledge, whether by hand or through agents, and more effort preserving the context that would otherwise disappear. AI is what finally makes that shift realistic.