Development projects rarely start with a clean sheet of paper. Every new feature, enhancement or migration inherits the consequences of decisions made years before. Teams often discover that seemingly straightforward changes become unexpectedly expensive, estimates become unreliable and developers hesitate to modify important parts of the system. We usually describe this phenomenon as technical debt.
Technical debt is often compared to financial debt. A shortcut taken today may accelerate delivery, but the resulting complexity must eventually be repaid through slower development, greater maintenance effort and increased risk. Left unmanaged, technical debt gradually reduces an organization’s ability to evolve its products.
Technical debt is commonly divided into several categories.
- There is code debt, where implementation has become unnecessarily difficult to maintain or extend.
- There is test debt, where insufficient automated regression testing reduces confidence that changes preserve existing behavior.
- And there is documentation debt, where documentation is missing, incomplete or outdated.
I have started wondering whether the third category describes the symptom rather than the underlying problem. Perhaps the deeper problem is understanding debt. Documentation is only one way of preserving understanding.
Understanding can also be lost because experienced people leave, architectural decisions are forgotten, business rationale disappears, names become disconnected from the problem domain, or relationships between artifacts are no longer visible.
The visible product survives. Its explanation does not. That changes the nature of the debt. Code debt makes implementation difficult. Test debt makes changes difficult to trust. Understanding debt makes it difficult to know what should be changed, what should remain unchanged, and why the system looks the way it does.
This distinction also helps explain something I have always appreciated about Behavior-Driven Development (BDD). BDD is often described as executable documentation. I still believe that is one of its greatest strengths. BDD preserves the observable behaviour of a system.
A scenario such as:
Given a Gold customer
When an order exceeds €50
Then shipping is free
tells future developers exactly what behaviour is expected.
But BDD deliberately answers a different question. It explains what the system should do. It does not attempt to explain why Gold customers receive free shipping.
Perhaps the rule originated from a marketing campaign, a contractual agreement, a legal obligation or a business strategy that has since changed. Those reasons belong somewhere else.
This made me realise that different product artifacts preserve different kinds of knowledge.
- Business decisions preserve intent.
- Architecture Decision Records preserve technical rationale.
- Architecture preserves structural decisions.
- Code preserves implementation.
- BDD scenarios and tests preserve expected behaviour.
- The Product Reference Model preserves where these artifacts live and how they relate to one another.
None of these artifacts should be expected to preserve everything. Together they preserve understanding. Understanding debt therefore cannot be solved simply by writing more documentation. It requires preserving the why, the how, and the what of the product. Only then can future teams reconstruct not merely how the system behaves, but why it became the system they inherited.
Perhaps documentation debt should therefore not disappear as a concept. Instead, it should be recognized as one of several causes of understanding debt. The objective is not to produce more documents. The objective is to preserve enough understanding that future people can continue the story instead of starting over.
Leave a Reply