Marcel van Oosterwijk

Category: Products

Products and systems as enduring subjects: their purpose, requirements, architecture, quality, operation, evolution, and the understanding needed to sustain them over time.

  • Practice Note: A Product Reference Model Is More Than Product Documentation

    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.

  • Practice Note: Ready, Done, and the Risk Between Them

    It is Friday afternoon. The end of the Sprint is approaching. Several stories are not finished and the pressure rises. A few tests could perhaps be skipped. A defect may not be serious enough to hold the story back. Regression testing could be completed later.

    Nobody says, “Let’s accept more product risk so that we can avoid Sprint spillover.” Yet that may be exactly what is happening.

    This made me look differently at the Definition of Done. Why are its criteria there in the first place? If testing, review, security checks or other quality controls are part of the DoD, they should not merely be activities the team has agreed to perform. They should be there because they control risks that matter.

    Seen that way, there are two quite different problems with a Definition of Done.

    The first is that it may not have been defined particularly well. It can become a generic checklist of things teams conventionally do rather than a set of controls related to the actual risks of the product.

    The second is that even a meaningful DoD may become negotiable when delivery pressure rises.

    “Can we skip this test so we can finish the Sprint?” sounds like a delivery question. But if the test exists to control a risk, the real question is closer to:

    What risk was this test controlling, and are we prepared to accept the residual risk without it?

    That may be a perfectly legitimate decision. The point is that it should be recognized as a risk decision. This suggests that risk should be made more explicit in the work itself.

    A user story normally contains intent and acceptance criteria. It could also identify the significant quality risks associated with the story: what might prevent the intended outcome, how likely that is, and how serious the consequences would be.

    Acceptance criteria and risk then serve related but different purposes. Acceptance criteria help us judge whether we implemented what we intended. Risk-based evidence helps us judge whether the important undesirable outcomes have been sufficiently controlled.

    That leads to an interesting reinterpretation of Ready and Done.

    The Definition of Ready becomes a shared checkpoint asking whether we understand the work — including its significant risks — sufficiently to start responsibly.

    The Definition of Done becomes the corresponding checkpoint at the other end: have those significant risks been sufficiently mitigated, and do we have appropriate evidence to support that judgment?

    In simple terms:

    Ready: do we understand the important risks sufficiently to proceed?

    Done: do we have sufficient evidence that those risks have been addressed to proceed further?

    But then another problem appears: stories do not exist independently.

    Story A can be Ready. Story B can be Ready. Story C can be Ready. Yet combining them in the same increment may create risks that none of the stories contains individually. They may change the same component. One may invalidate assumptions made by another. Performance, security, resilience or operational complexity may emerge only when the changes interact. So readiness has an increment aspect too.

    It is not enough to ask whether the individual stories are Ready. We also need to ask whether we understand the significant risks created by combining them.

    The same applies to Done. Three stories can individually satisfy their DoD while the integrated increment still behaves unacceptably.

    A set of Done stories does not automatically make a Done increment.

    As work aggregates, risk can emerge at the new level. Assurance therefore has to aggregate with it.

    The same logic can continue toward release. A completed increment can still be unsuitable for deployment because release and operational risks only become meaningful at that level.

    What started as a Scrum mechanism therefore begins to look more like a broader assurance chain:

    Intent → Risk → Control → Evidence → Judgment

    At each level, we are asking what we are trying to achieve, what could prevent it, what controls those risks, what evidence we have, and whether the remaining risk is acceptable.

    And the chain should not end when the release reaches production. Production gives us new evidence. Some risks materialize despite our controls. Some turn out to have been underestimated. Others were never identified at all.

    Eventually, the production defect may come back to the development team. But the more important question is:

    Did the defect come back, or did the lesson come back?

    If an incident reveals that a risk was missed, misunderstood or inadequately controlled, that knowledge should change future stories, risk assessments, controls, and perhaps even what Ready and Done mean.

    The loop becomes something like:

    Ready → Develop → Done → Integrate → Release → Operate → Learn → Ready…

    The product continues, and so should our understanding of its quality.

    The principle that seems to emerge is simple:

    As work aggregates, assurance must aggregate with it.

    That turns Ready and Done from static checklists into checkpoints in a continuous quality-learning system.

  • Practice Note: Product Requirements for Operations

    We are used to translating product intent into requirements for development.

    We want to achieve something, so we determine what the product needs to do. Development implements it. Testing gives us evidence that it works. Eventually, we decide that the product is good enough to release.

    But development is only a means to an end.

    We do not build $shiny_new_function because the world needs another successfully implemented function. We build it because we expect something to happen once people start using it.

    Suppose $shiny_new_function has been implemented correctly. It produces the right results, performs well, is secure, handles the expected load and passes all its tests. Development has done an excellent job.

    Now suppose that, according to the original intent, success also meant that the function would be used at least 500 times per day.

    Three months after release, it is being used 17 times per day.

    Is the product good? That is a surprisingly different question from whether it was implemented correctly.

    Before release, we could test whether the function can handle 500 uses per day. We could simulate the load and collect evidence that the implementation is capable of doing what we expect.

    But no test can establish that real users will actually use it 500 times per day. For that, we need reality.

    This suggests that when we translate intent into requirements, we may be doing only half the job.

    We are quite accustomed to asking:

    What do we need to build to achieve this intent?

    Perhaps we should simultaneously ask:

    What would we need to observe in operation to know whether we actually achieved it?

    The first question gives Development something to realize.

    The second gives Operations something to observe.

    If the intent is to reduce customer effort through a new self-service capability, we will probably derive requirements describing what that capability must do.

    But if reduced customer effort is really what matters, we should also know what we expect to see once the capability is operating. Are customers actually using it? Are they completing the process? Where are they abandoning it? Are fewer customers contacting support? Has customer effort actually decreased?

    Those aren’t merely interesting metrics to add to an operational dashboard. They are evidence about whether the product is doing what we created it to do. And that means we may need to think about them before the product reaches production.

    If we want to know how $shiny_new_function is being used, we need to make that usage observable. If we want to understand where users abandon a process, we need to capture the relevant events. If we want to know whether self-service reduces support demand, we need some way of connecting those pieces of information.

    Otherwise, we may arrive in production and discover that we cannot answer one of the most important questions about the product:

    Is it actually working as intended?

    Not whether the software is running. Not whether the implementation satisfies its requirements. Whether the thing we built is actually producing the effect for which we built it.

    This is where production becomes particularly interesting for quality.

    Before release, much of our evidence necessarily concerns what we expect to happen. Requirements, reviews, tests and simulations can give us confidence that our realization is capable of fulfilling the intent.

    After release, we get something we did not have before. We get to see what actually happens. And reality may disagree with us.

    If $shiny_new_function works perfectly but receives only 17 of the expected 500 uses per day, that does not immediately tell us what is wrong. Perhaps users cannot find it. Perhaps they do not trust it. Perhaps another way of doing the same thing is easier. Perhaps we misunderstood their needs. Perhaps the assumption behind 500 uses per day was wrong. Perhaps 17 uses are actually enough to produce the business outcome we wanted, and we chose the wrong success criterion.

    Some of those answers would lead us back to Development. Others would lead us much further back, to our assumptions and even to the original intent.

    That is why a production observation should not merely become another defect or improvement ticket. It should become learning.

    Quality work has traditionally put enormous effort into determining whether something is good enough to enter production. That remains important. We need evidence that the realization is sufficiently sound before exposing it to reality.

    But perhaps we have concentrated too much on the means and not enough on the end.

    A product does not become successful because it passed its release assessment. That only means we had sufficient confidence to let it start doing the job for which it exists. The more important assessment begins when it actually does.

    So perhaps product intent should point in two directions from the beginning. It should tell Development what needs to be realized. And it should tell Operations what needs to be observed.

    One gives us evidence that the product can do what we intended. The other gives us evidence about whether it does.

    And the difference between those two is where some of our most valuable learning may be found.

  • Practice Note: From Product Management to Subject Management?

    This note is deliberately speculative. It takes a pattern that emerged through work on Product Continuity and organizational capabilities and asks whether that pattern might point toward something more general. I do not know whether the generalization holds, and I am certainly not proposing a new universal definition of management.

    But the pattern has become interesting enough to record.

    Starting With Product Continuity

    None of this began as an attempt to understand management.

    It began with Product Continuity and a relatively practical problem: products often live much longer than the organizational understanding that created them. People leave, responsibilities move, decisions accumulate and circumstances change. The product continues to develop, but the understanding connecting its purpose, design, operation and evolution can become increasingly fragmented.

    That led to the idea of a Product Reference Model: an explicit representation of the significant understanding needed to develop and assess the product over time.

    Initially, that seemed primarily like a continuity mechanism. If important intent, expectations, assumptions, boundaries and rationale could be made explicit, future development would not have to depend entirely on organizational memory.

    But once the reference existed conceptually, it became difficult to limit its role to preservation.

    The same understanding that describes what the product is intended to accomplish can guide its development. It can also provide the reference against which the realized product is assessed. Assessment produces evidence and judgment, which in turn create learning. That learning may change not only the product but our understanding of what the product should become.

    The result is a continuing cycle rather than a static document:

    Reference → Development → Realization → Assessment → Learning → revised Reference

    And because the cycle continues as people, circumstances and products change, someone must preserve its coherence over time.

    That is where Product Continuity began to look remarkably like something we already have: Product Management.

    Looking Again at Product Management

    Product Management is already concerned with many of these things. It maintains product direction, connects products to customer and business needs, guides priorities and development, considers evidence from the market and the realized product, and continues doing so as the product evolves.

    Product Managers do not personally perform all the activities involved. They are not necessarily the architects, developers, testers, designers, analysts or operators. Specialist responsibilities remain distributed.

    What Product Management provides is continuity around the product itself.

    Seen through the lens of Product Continuity, those familiar responsibilities appear to form a recognizable architecture. There is some understanding of what the product should accomplish. The product is deliberately developed against that understanding. The resulting product and its outcomes are continually observed and judged. Evidence produces learning. That learning influences subsequent direction and development. And throughout this process, Product Management provides continuing stewardship of the subject while specialist disciplines contribute to it.

    This does not redefine Product Management. If anything, it offers a possible explanation for why responsibilities that may otherwise appear quite different belong together.

    Then the Same Pattern Appeared Somewhere Else

    The interesting part came when thinking about organizational capabilities.

    A capability also needs some explicit understanding of what organizational ability is required and why. That can be represented through a Capability Reference Model. The capability can be assessed against that reference to understand the organizational ability that actually exists. It can be deliberately developed where change is needed. Assessment and experience create learning, which may change both the realized capability and our understanding of what capability is required. And because improvement projects eventually end while the organizational capability continues, somebody may need to preserve its development and coherence over time.

    That led to the speculative idea of Capability Management. At that point, the similarity became difficult to ignore. The subject had changed. The architecture had not.

    Is the Product Special?

    That raises a question I had not originally intended to ask. What if Product Management and Capability Management are not merely two unrelated disciplines that happen to contain similar activities? What if they are two specializations of a more general pattern? For lack of a better term, I will call that pattern Subject Management.

    A subject, in this sense, is simply whatever we are deliberately trying to preserve, understand, develop and assess over time. A product can be such a subject. An organizational capability can be one. A portfolio may perhaps be another.

    Subject Management could then be tentatively understood as the continuing stewardship of such a subject through an explicit reference, recurring assessment, deliberate development and learning.

    The reference describes the significant understanding against which development and judgment can take place. Development deliberately changes the subject. Assessment establishes what has actually been realized and how well it satisfies the reference. Learning feeds the resulting understanding back into future decisions. Stewardship preserves coherence across that cycle as circumstances change.

    This is not necessarily a sequence of management activities. Stewardship may be better understood as the responsibility surrounding the whole cycle.

    Where the Generalization Stops

    There is an obvious danger in taking this too far. Management is an enormous concept. Organizations manage people, money, resources, suppliers, risks, operations, conflicts and countless other things. I have no basis for claiming that all of management can be reduced to reference models, assessment, development and learning.

    Nor does this idea imply that established disciplines such as Product Management are merely implementations of a new abstract theory.

    The observation is much narrower.

    Some subjects persist over time while both the subjects themselves and the circumstances around them change. Where organizations deliberately care about the continued suitability of such a subject, a recurring pattern appears plausible: maintain an explicit understanding of what matters, assess reality against that understanding, deliberately develop the subject, learn from the resulting evidence and preserve continuity across the whole process.

    I have seen enough of that pattern in products and capabilities to wonder whether it is more general. I have not seen enough to conclude that it is. That distinction matters.

    An Abstraction That Emerged Afterwards

    Perhaps the most important reason to record this idea is the way it appeared. I did not begin by defining Subject Management and then search for examples that fitted it. I began with Product Continuity.

    Product Continuity led toward explicit Product References. Those references turned out to support both development and assessment. Assessment introduced evidence and learning. The continuing cycle created a need for stewardship. Only then did the resulting structure begin to resemble an underlying architecture of Product Management.

    When essentially the same pattern appeared while thinking about organizational capabilities, the possibility of a more general abstraction emerged. The abstraction therefore came afterwards. Whether it survives further examination is another question.

    It may turn out that products and capabilities are similar in ways that make the pattern appear more general than it really is. Other subjects may expose important missing elements. Existing management theory may already describe the same pattern using better concepts. Or the idea may prove useful only within the narrower theory of Continuity from which it emerged.

    Any of those outcomes would be useful.

    For now, the observation is simply this:

    Product Management appears to provide continuing stewardship of a product through reference, development, assessment and learning. Capability Management may require a remarkably similar architecture.

    If that similarity is not accidental, perhaps the next question is no longer only what Product Management or Capability Management means. Perhaps it is:

    What kind of subject requires management in the first place?

  • Practice Note: How many systems did you retire last year?

    Organizations often associate continuity with keeping systems, products, or capabilities running. Yet continuity can require the opposite: knowing when something can safely cease to exist.

    A mature portfolio does not only make informed decisions about what to add. It also makes informed decisions about what to remove.

    One provocative measure of product-portfolio maturity is therefore the number of systems an organization has been able to retire. The measure should not be taken literally—retiring more systems is not inherently better—but the reasoning behind it is revealing. Retiring a system confidently requires understanding what the system still contributes and what depends upon it.

    Consider an old mainframe environment.

    Over many years, applications may have been migrated elsewhere. New development has stopped. Most known business functionality has disappeared. The organization believes that the mainframe has effectively become redundant.

    Yet it remains operational. Why? Because nobody is sufficiently confident that it can be switched off.

    There might still be a batch process running somewhere. An obscure interface may still exchange data with another system. A business process performed only once a year may depend upon it. Some responsibility may have been assumed to have migrated but never actually did.

    The organization does not know that the mainframe is necessary. It does not know that it is unnecessary. That distinction can keep an obsolete system alive for years. Loss of understanding can preserve obsolete realizations

    This exposes an interesting inversion. Normally, understanding is associated with an organization’s ability to maintain and develop something. But understanding is equally important when deciding to stop maintaining it.

    As organizational understanding disappears, the realization can become increasingly difficult to change or remove. Its known value may decrease while uncertainty about its unknown value increases.

    Eventually the organization may preserve the realization not because it believes the realization is valuable, but because it cannot establish that removing it is safe.

    Loss of understanding can increase the persistence of something whose value has already disappeared.

    The resulting portfolio contains systems that survive through uncertainty.

    They consume infrastructure, licenses, operational effort and scarce expertise. They may constrain architectural change and introduce security or operational risks. Yet attempts to remove them encounter the same question:

    Are we absolutely sure nothing important still depends on this?

    Without sufficient understanding, the organization cannot answer.

    Retirement is an assessment problem

    Retiring a system is therefore not merely a technical activity. It requires an assessment. The organization needs sufficient understanding of the system’s purpose, current contribution, dependencies, users, data, business processes and outcomes to form a justified judgment about what will happen when it disappears.

    Evidence may need to be collected: usage information, interface traffic, batch execution, dependency analysis, business-process mapping, stakeholder knowledge or controlled interruption.

    The question is not simply whether the system appears obsolete.

    The question is whether there is sufficient evidence and understanding to justify the judgment that its removal is safe.

    This connects retirement directly to Continuity.

    Continuity does not mean preservation of the object

    Continuity can easily be misunderstood as an argument for keeping things alive. It is not.

    The continuity that matters is continuity of what remains significant: intent, outcomes, responsibilities, knowledge and necessary relationships. A particular realization may cease to be the appropriate way of providing them.

    Sometimes maintaining Continuity therefore requires replacing a system. Sometimes it requires transferring responsibilities elsewhere. Sometimes the purpose itself has disappeared and nothing needs to replace it. And sometimes the correct decision is simply to switch the system off.

    The ability to make that decision confidently depends on understanding.

    Poor Continuity may not cause an old system to disappear. It may be precisely why nobody dares to switch it off.

    The portfolio implication

    This has consequences for portfolio management. Portfolio development is often associated with investment: selecting new products, approving initiatives and allocating resources to new opportunities.

    But a portfolio also develops through subtraction. Removing redundant elements releases resources, reduces complexity and risk, and allows investment to concentrate on elements that continue to contribute to portfolio intent.

    A mature portfolio-management capability therefore needs to understand its existing portfolio well enough to answer not only:

    What should we add?

    but also:

    What can we safely stop?

    This makes retirement capability an interesting indicator of portfolio understanding. An organization that continually adds new systems but cannot confidently retire old ones may not have a technology problem at all.

    It may have accumulated understanding debt at portfolio scale.

    And I think this one is particularly valuable because it produced a candidate generic insight for A:

    Sufficient understanding is required not only to develop and assess a subject, but also to determine when it can safely cease to exist.