An organization has a software product.
It has requirements, architecture documentation, source code, test results, incident reports and records of important decisions.
Everything appears to be documented.
But ask a simple question:
Why does this product exist?
The answer may be surprisingly difficult to reconstruct.
Ask which organizational capabilities depend on it, why its architecture looks the way it does, or what evidence demonstrates that it remains fit for purpose, and the problem becomes even more apparent.
The information may exist.
But that doesn’t necessarily mean the organization can use it to understand the product.
Documentation Is Not Understanding
Product documentation usually describes particular aspects of a product.
Requirements describe expected behaviour. Architecture models describe structure. Test results provide evidence about certain characteristics. Decision records explain selected choices.
Each artifact serves a purpose.
But understanding a product requires more than understanding its individual artifacts.
It requires understanding their relationships.
Why was a particular architectural decision made? Which requirement or quality expectation motivated it? What alternatives were considered? What evidence supported the decision?
And perhaps more importantly, does the original reasoning still hold?
A collection of individually useful documents does not automatically provide a coherent understanding of the product.
From Reference Model to Product Model
This is where a product reference model becomes interesting.
A product reference model describes the concepts and relationships we consider relevant when understanding products.
For example, a product has a purpose. It supports organizational capabilities. It has expected behaviours and characteristics. It has an architecture and a realization. Decisions shape its development, and evidence supports claims about its qualities.
These concepts are generic.
They do not describe any particular product.
A product model applies them to a specific product, connecting its actual purpose, characteristics, architecture, decisions and evidence.
The distinction matters.
The reference model provides a common structure for reasoning.
The product model represents our understanding of a particular product.
The documentation supplies much of the information and evidence on which that understanding depends.
A reference model is therefore not another documentation template.
It helps us understand how different pieces of information relate.
Connecting the Product to Its Purpose
Consider an organization replacing a legacy system.
The replacement project may produce extensive documentation. The new system may satisfy its requirements and pass its acceptance tests.
But why was the system replaced?
Perhaps the old system prevented the organization from responding quickly to changing customer needs.
In that case, the replacement is not merely a technical exercise.
It is an intervention intended to improve an organizational capability.
Understanding the product therefore requires connecting its technical characteristics to the organizational purpose it serves.
Which capabilities depend on it?
Which limitations of the previous system motivated the replacement?
Which characteristics of the new product are expected to address those limitations?
And what evidence would demonstrate that the intended improvement has actually occurred?
These relationships may be more important than any individual document.
Without them, we may know a great deal about how the product works while knowing surprisingly little about whether it achieves its purpose.
Understanding What We Don’t Know
There is another benefit to making these relationships explicit.
We can begin to identify gaps in our understanding.
Perhaps an architectural decision exists without a recorded rationale.
Perhaps a quality requirement has no supporting evidence.
Perhaps a product supports an important organizational capability, but nobody has established whether the product remains adequate for that purpose.
Or perhaps a decision was justified by assumptions that are no longer valid.
A product model doesn’t automatically resolve these uncertainties.
But it can make them visible.
And that changes how we think about completeness.
The objective is not necessarily to produce more documentation.
It is to establish whether we have sufficient understanding and evidence to manage the product responsibly.
The Product Outlives the Project
Products often continue long after the projects that created them have ended.
The original architects leave. Development teams change. Technologies evolve. New requirements emerge.
Yet the product must still be understood, maintained, assessed and developed.
Traditional documentation can preserve valuable information, but it may not preserve the relationships needed to interpret that information.
A product model could provide continuity.
Not by anticipating every question future people might ask, but by maintaining a coherent representation of the product and its relationship to organizational intent, decisions and evidence.
It could also make that understanding easier to interrogate.
Why was this component introduced? Which capabilities would be affected if we removed it? What evidence supports the assumption that this design remains appropriate?
The answers may require information from several sources.
The reference model helps establish how those sources relate.
More Than Documentation
Perhaps the important distinction is not between having documentation and having a model.
Both can be useful.
The distinction is between preserving information about a product and maintaining an understanding of the product as a subject that must continue to be managed.
A product reference model provides the conceptual structure.
A product model applies that structure to a particular product.
Documentation and other evidence support the resulting understanding.
Documenting a product helps us preserve what we know about it.
Modeling a product helps us understand how that knowledge relates — and what we still don’t know.
Leave a Reply