Category: Practice Notes

When I first imagined a Product Reference Model, I thought of it as another repository for product knowledge. I no longer think that is the right mental model.

A product already contains many repositories:

• The Product Owner maintains the backlog.
• Enterprise Architects maintain architecture models and Architecture Decision Records.
• Developers maintain source code.
• QA maintains assessments, test strategies and quality evidence.
• Operations maintains runbooks and operational procedures.
• Security teams maintain security documentation.

Every discipline already has tools and repositories that support its own work. The Product Reference Model should not replace them. Instead, it should index them. For every significant artifact, it should make clear:

• What is this artifact?
• Where can it be found?
• Who owns it?
• Why does it exist?
• How does it relate to the rest of the product?
• Who depends on it?
• Can everyone who needs it access it?

The detailed knowledge remains within the artifact itself. The Product Reference Model provides the shared navigation structure through which that knowledge can be discovered and understood.

This distinction is important. The Product Reference Model is not another documentation repository.

It is a lightweight knowledge architecture.

Perhaps Enterprise Architecture provides the right inspiration. Enterprise Architects have spent decades thinking about repositories, viewpoints, relationships, governance and traceability across an enterprise.

The Product Reference Model applies many of those same principles at the scale of a single product. Rather than describing how an enterprise fits together, it describes how one product remains understandable throughout its lifecycle.

Preserve knowledge where it belongs

The Product Reference Model should duplicate as little information as possible. Every artifact should preserve its own knowledge.

Requirements should explain the need behind them. Architecture Decision Records should preserve the trade-offs behind important decisions. BDD scenarios should preserve expected behavior. Operational procedures should explain the situations they were created for.

Whenever an artifact already contains sufficient rationale, the Product Reference Model simply links to it. Whenever the rationale is missing, the Product Reference Model becomes the place where that missing understanding is preserved.

The objective is therefore not more documentation. The objective is preserving understanding.

A federated knowledge model

The Product Reference Model also changes how I think about collaboration. Initially I believed that every stakeholder simply contributes information and everyone benefits.

That is true, but incomplete: every stakeholder already possesses unique understanding. The Product Owner understands business intent. Architects understand structural decisions. Developers understand implementation. QA understands quality and evidence. Operations understands behavior in production.

No single discipline possesses the complete understanding of the product. The Product Reference Model therefore creates a federated knowledge model.

Each stakeholder maintains ownership of their own artifacts while making that understanding discoverable to everyone else. Ownership remains distributed. Understanding becomes shared.The Product Owner does not become an architect. The architect does not become a tester. QA does not become an operations engineer. Every discipline remains responsible for its own expertise.

The Product Reference Model simply allows everyone to benefit from the expertise maintained by every other discipline.

Knowledge amplification

This also reveals the true value of the Product Reference Model. It does not create new knowledge. It amplifies the value of knowledge that already exists. Without the Product Reference Model, every discipline works largely within its own information space. With the Product Reference Model, each discipline gains visibility into the understanding maintained by all the others. The Product Owner better understands architectural constraints. The architect better understands business intent. QA better understands operational realities. Operations better understands the reasons behind design decisions. Developers better understand business priorities.

Collective understanding increases without requiring everyone to become an expert in every discipline. Its value is therefore not additive. It is multiplicative. Every additional viewpoint increases the value of all the others.

A practical implementation

The Product Reference Model could simply exist as a structured wiki or similar workspace. Rather than storing all product knowledge itself, it provides a consistent structure through which stakeholders expose the artifacts they already own. Each section contains references to relevant artifacts together with any rationale that is missing from those artifacts themselves. The Product Reference Model therefore becomes the product’s navigation layer rather than its documentation repository.

A simple definition

Perhaps the Product Reference Model can be summarized as follows:

The Product Reference Model is a federated knowledge architecture that indexes the significant artifacts of a product, preserves their relationships and rationale, and amplifies collective understanding by allowing every stakeholder to contribute the understanding they already possess while gaining access to the understanding maintained by every other stakeholder.

Design principles

• The Product Reference Model should contain as little duplicated information as possible.
• Knowledge remains with the artifact that owns it.
• Understanding is created by connecting those artifacts.
• Every significant artifact should preserve not only what it contains, but also why it exists.
• Every stakeholder contributes local understanding.
• Every stakeholder gains systemic understanding.

While watching the TV-show Pluribus, one particular idea stayed with me long after the story ended.

The series imagines that the accumulated knowledge of an individual could be transferred into something larger than themselves. In the story, this becomes a collective intelligence. Whether such a future is desirable is another discussion entirely.

What fascinated me was the question behind it: How much of what a person knows disappears when that person dies?

A few months before my mother passed away, we discussed a question that has remained with me ever since:

“How can I dump everything in my head into something external so that it will survive me?”

We were not talking about books or photographs. We were talking about understanding. The memories. The explanations. The reasons behind decisions. The connections between seemingly unrelated events. The answers to questions nobody had yet thought to ask.

Since then I have begun noticing the same pattern everywhere. When my parents died, many possessions remained, but not always the stories that explained why they mattered. In software, source code often survives while the business rationale disappears. Organizations inherit systems but lose the people who understood them.

Perhaps this is not really a software problem. Perhaps it is a human problem. Pluribus imagines one possible answer: preserve everything. Reality is unlikely to offer such a perfect solution.

Yet perhaps we do not need to preserve everything. Perhaps we simply need to become better at preserving the answers to the important questions while the people who know those answers are still able to tell them.

Artificial intelligence may eventually become the interface to that preserved understanding. But it cannot preserve what was never recorded. That responsibility still belongs to us.

As children, we ask endless questions. Why is the sky blue? Why do birds fly? Why do we have to go to school?

At some point, most of us stop asking. Perhaps we have built a sufficiently complete mental model of the world to function without constantly questioning it. We become occupied with doing rather than understanding.

I have noticed something else. The real problem is not that people stop asking. It is that we stop preserving the answers.

I experienced this personally after both my parents passed away. They left behind many possessions, but not always the stories that explained why those possessions mattered. Some objects remained meaningful because I already knew their history. Others became impossible to interpret. Without their explanation, they became little more than objects.

I have seen exactly the same phenomenon in software. In one company, existing business process descriptions were discarded because they were considered unnecessary. Later, during acceptance testing, we had to reconstruct those very processes from scratch because nobody could confidently explain how the business was supposed to work.

The software survived. The answers did not. That experience made me realise that documentation is often misunderstood.

We tend to think documentation exists to describe systems. Perhaps its deeper purpose is to preserve the answers to the important questions, like:

• Why does this product exist?
• Why was this architectural decision made?
• Why does this business rule exist?
• Why is this object important?

The answers may be preserved in different places. BDD scenarios preserve answers about expected behavior. Architecture Decision Records preserve answers about technical choices. Business documentation preserves answers about organizational intent. Even personal stories preserve answers about why certain possessions became meaningful.

No single document can answer every question. What matters is that the answers survive somewhere. Increasingly I find myself thinking that good stewardship—whether of software, products or personal history—is not about preserving artifacts. It is about preserving the understanding that makes those artifacts meaningful.

Perhaps every generation inherits objects. Our responsibility is to ensure they also inherit the answers.

For new functionality, the Why still exists in people’s heads and conversations. AI can help surface it before it disappears. During refinement or design discussions, it could ask why the functionality is needed, whose problem it solves, which outcome it should influence, what assumptions shape it, and under what circumstances it would no longer be necessary.

In that setting, AI should not invent the Why from a user story after the discussion has ended. It should help people articulate, challenge and preserve the Why while the decision is being made.

Existing functionality presents a different problem. The people who made the decision may have left, and the original rationale may never have been recorded. AI can inspect the surviving evidence: code, BDD scenarios, tests, backlog history, commit messages, architecture decisions, support incidents and business documents. From these fragments, it may be able to reconstruct a likely explanation.

But a likely explanation is not necessarily the original explanation. AI may recover what the system does and reconstruct how it does it. It can also propose why that behavior might exist. Yet where the original Why left no trace, AI cannot restore history with certainty. It can only form a hypothesis.

That means an AI-generated Why should carry an explicit status:

• Recorded — directly supported by an authoritative source.
• Corroborated — supported by several independent pieces of evidence.
• Inferred — plausible, but not directly evidenced.
• Unknown — no defensible explanation can be reconstructed.

This may be where AI becomes most valuable: not by filling every blank with persuasive prose, but by distinguishing recovered understanding from inferred understanding and genuine gaps.

For existing systems, AI could act as an investigator. It could identify functionality whose rationale is preserved, functionality whose rationale is merely implied, contradictory explanations, and areas where interviews are still needed before the remaining human knowledge disappears.

For new systems, it could act as a facilitator. It could ensure that the Why is captured alongside the How and the What rather than being left behind in a meeting.

The two uses are complementary:

Prospectively, AI can help prevent understanding debt. Retrospectively, it can help repay it.

But it cannot manufacture certainty.

Perhaps the most important role for AI is therefore not answering every Why. It is helping us see which Whys are known, which are inferred, and which have already been lost.

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.