Blog

  • 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: AI and the Succession of Understanding

    Much of the discussion about AI and software development focuses on whether AI will replace developers.

    A different risk may be emerging.

    Organizations may use AI to automate precisely the work through which people traditionally developed the understanding required to become senior.

    Senior developers did not enter organizations as senior developers. Their expertise accumulated over time.

    They implemented small changes. They investigated defects. They read unfamiliar code. They made mistakes. They observed production failures. They asked why something had been designed in a particular way. They discovered that apparently strange implementations sometimes existed for good reasons — and sometimes for reasons that had stopped being good years earlier.

    Through repeated exposure, they acquired more than technical skill.

    They acquired context.

    They learned not only what the system does, but increasingly why it became the way it is.

    The Efficiency Paradox

    AI can remove substantial amounts of routine work from software development. That can be valuable.

    A junior developer may no longer need to spend hours writing relatively straightforward implementation code, searching documentation, constructing tests, investigating logs or performing other work that an AI system can complete much faster. Measured as delivery efficiency, this looks like progress.

    But some apparently inefficient work may have performed another function:

    It created experienced people.

    The work product was not its only output.

    Learning was another.

    If we automate the activity while measuring only whether the immediate deliverable can still be produced, we may overlook the organizational capability that the activity was helping to create.

    Work Has More Than One Outcome

    This suggests a more general distinction.

    An activity may produce an explicit outcome and one or more implicit outcomes.

    For example:

    Explicit outcome:
    – A developer fixes a defect.

    Implicit outcomes:
    – The developer learns how the system behaves.
    – They discover relationships between components.
    – They understand why a particular design decision matters.
    – They encounter a business rule that was previously invisible to them.
    – They become better able to recognize similar problems in the future.

    An AI system may produce the explicit outcome extremely efficiently while reducing some of the implicit outcomes.

    The defect still gets fixed. But who learned from fixing it?

    The Succession Problem

    This becomes particularly important when experienced people leave.

    Organizations already struggle to preserve understanding across personnel changes. Documentation may preserve requirements, architecture, code and decisions while much of the reasoning connecting them remains in people’s heads.

    AI could introduce a second continuity problem. It may not only change how existing knowledge is preserved.

    It may change how new people acquire enough understanding to become future custodians of that knowledge.

    If today’s senior developers retire or leave, organizations cannot simply replace them with today’s juniors plus more capable AI.

    The question is whether those juniors have had opportunities to develop the contextual and causal understanding that made the departing developers senior in the first place. This is therefore not merely a staffing pipeline problem.

    It is a succession of understanding problem.

    Expertise Is More Than Accumulated Information

    It would be tempting to solve this by giving future developers better access to documentation and AI-generated explanations. That will help, but it may not be sufficient.

    Experienced practitioners possess more facts, but they also have developed judgment.

    They recognize when something looks suspicious before they can necessarily explain exactly why. They know which questions to ask. They recognize recurring causal patterns. They understand where apparently local changes may have wider consequences. Much of that ability was developed through interaction with real problems.

    The challenge is therefore not simply to transfer everything a senior developer knows to a junior developer.

    It is also to preserve opportunities through which less experienced people can develop their own understanding and judgment.

    AI Changes the Learning Path

    This does not imply that organizations should preserve inefficient manual work simply because previous generations learned through it. That would confuse the practice with the function it served.

    The important question is instead:

    Which learning functions did the old way of working provide, and how will those functions be preserved when AI changes the work?

    Perhaps some learning can happen faster with AI. AI can explain unfamiliar code, expose dependencies, challenge assumptions, simulate alternatives and make organizational knowledge easier to interrogate.

    Used deliberately, it may accelerate the development of understanding rather than diminish it.

    But that requires designing AI-supported work for more than immediate productivity.

    The objective cannot only be:

    How can AI help this developer produce the result faster?

    It must also include:

    How does this developer become capable of understanding, questioning and eventually owning the results?

    Implication for Continuity of Understanding

    Continuity of understanding therefore has at least two dimensions.

    The first is preservation:

    Can the organization retain enough of its existing understanding when people leave, systems change and structures evolve?

    The second is regeneration:

    Can new people develop enough understanding to extend, challenge and eventually replace the understanding held by today’s experts?

    A reference model can help with the first by connecting fragmented knowledge and preserving relationships, rationale and intent.

    But it may also support the second. If important relationships between intent, requirements, decisions, implementation, evidence and outcomes are made accessible, a less experienced person does not have to reconstruct all of them accidentally over years of work.

    They can explore them deliberately.

    AI may make that exploration dramatically easier.

    The opportunity is therefore larger than preserving the old apprenticeship model.

    It is to create a better one.

    Working Proposition

    AI should not only increase the productivity of today’s experts. It should help create tomorrow’s experts.

    When evaluating AI-supported ways of working, organizations should therefore assess not only:

    • whether work is completed faster,
    • whether fewer people are required,
    • whether output quality remains acceptable,

    but also:

    • whether practitioners continue to develop contextual understanding,
    • whether reasoning and rationale remain accessible,
    • whether people learn from the work AI performs with them,
    • whether judgment and ownership continue to develop,
    • and whether the organization is creating the people who will be capable of carrying its understanding forward.

    Otherwise, AI may solve today’s capacity problem while quietly creating tomorrow’s capability problem.

  • Practice Note: The Recursive Why

    There is a recursive quality to the question why that I find fascinating.

    Suppose we are automating regression testing. Why are we doing that? Perhaps because we want confidence that changes have not broken existing behavior. But that answer can itself become the subject of the next question. Why do we need that confidence? Perhaps because we want to release changes without creating unacceptable risk. Why do we want to do that? Perhaps because the product needs to respond quickly to changing needs.

    Something interesting happens as we move through these questions. The answer to why at one level becomes the what at the level above it.

    Automated regression testing is a What whose Why is confidence in changes. Confidence in changes is then itself a What whose Why is the ability to release safely. The ability to release safely becomes another What, connected to another Why.

    The Why of one layer is the What of the layer above it.

    This suggests that Why is not simply an explanation attached to something. It is a connection between levels. The higher level gives purpose to the level below it, while the lower level is one way of contributing to what the higher level is trying to achieve.

    Perhaps this is also an important part of what we mean by understanding.

    We can know a great deal about something without necessarily understanding it. We can know what a system does, what requirements it has, what decisions were made, what processes people follow, and what technologies are used. But if we can no longer move from those Whats toward the Whys that give them meaning, something important has been lost.

    A requirement without its Why becomes an isolated statement. A design decision without its Why becomes an historical fact. A process without its Why becomes a sequence of activities that may continue long after anyone can explain what capability those activities were intended to provide.

    The information may still be there. The understanding is not.

    This also means that Why has no obvious natural endpoint. Every answer can potentially become the subject of another Why. Eventually we stop, but perhaps not because we have reached some ultimate Why. We stop because we have reached a boundary that is sufficient for what we are currently trying to understand.

    That makes the choice of boundary important. If we draw it too narrowly, the Why may sit outside it. We can then describe the subject in extraordinary detail while remaining unable to explain its purpose. We may even optimize it successfully according to its internal logic while losing sight of whether it still contributes to what matters at the level above.

    Perhaps understanding, then, does not primarily reside in the individual pieces of information we preserve.

    It resides in the connections between them.

    And perhaps one of the most important connections we can preserve is the one that allows us to keep asking:

    Why?

    Come to think of it, Why? may be the most frequently asked question in the universe. After all, every answer gives us something new to ask Why? about.

  • Practice Note: From Assessment Model to Assessment Approach

    Earlier Practice Notes use the term Assessment Model to describe the way an assessment is structured and performed.

    I have come to think that Assessment Approach is a better term.

    The distinction matters because a Reference Model and an Assessment Approach are not the same kind of thing.

    A Reference Model describes what we assess against. It makes explicit our understanding of the subject: its purpose, expected qualities, characteristics, relationships, constraints, or other aspects relevant to judging it.

    An Assessment Approach describes how we perform the assessment. It determines how we investigate the subject, what evidence we seek, how we collect and interpret that evidence, and how we arrive at justified judgments.

    Put simply:

    Reference Model = what we assess against.

    Assessment Approach = how we assess.

    Calling both of these things models creates an unnecessary symmetry between them. The Reference Model represents an understanding of the subject. The Assessment Approach is the means by which we investigate reality in relation to that reference.

    This Practice Note therefore introduces a terminology change.

    From this point onward, I will use Assessment Approach rather than Assessment Model.

    Earlier Practice Notes will remain unchanged. Where they use Assessment Model in this sense, it should generally be understood as what I would now call an Assessment Approach.

    This is not a change to the underlying ideas in those notes. It is a refinement of the language used to express them.

    And perhaps there is a broader principle here as well.

    A developing body of knowledge does not need to rewrite its past every time its language improves. Earlier thinking can remain visible while later notes clarify, refine, or supersede it.

    The history of the terminology then becomes part of the history of the understanding.

  • Practice Note: The Death of the Predefined Representation?

    In The Death of the Document?, I explored a simple possibility: perhaps documents are no longer always necessary as the primary way in which knowledge is transferred.

    Traditionally, a document has to be created before somebody knows exactly what they will want from it. An author decides what matters, how the material should be structured, how much detail should be included and in which order it should be presented. The reader then works through that predefined representation in order to extract whatever understanding is relevant to the question they actually have.

    The sequence is familiar:

    Knowledge → Publication → Reading → Understanding

    AI makes another sequence possible:

    Knowledge → Question → Synthesis

    The answer no longer necessarily has to be published before the question exists. A representation can be created because somebody asks for it.

    At first, this appears to be a question about documents. But once the idea is taken seriously, the same pattern starts appearing elsewhere.

    A Dashboard Is Also a Predefined Answer

    Consider a dashboard. A dashboard is an attempt to anticipate future questions. Someone decides that users will probably want to know how much was sold today, whether sales are rising or falling, which regions are underperforming, how margins are developing, and perhaps a dozen other things. Measures are selected, charts are designed, filters are added and drill-down paths are created. If the resulting dashboard cannot answer a particular question, somebody may eventually build a custom report. All of this happens before the user actually asks anything.

    Now imagine that the user can simply say:

    How much did we sell today?

    The system answers.

    Why is that lower than yesterday?

    It investigates.

    Is Sweden causing it?

    It investigates again.

    Then what is causing it?

    The next answer is synthesized from whatever data is relevant.

    The important change is not merely that the dashboard has become easier to use. The sequence of questions no longer has to be designed in advance. Each new question can emerge naturally from the answer to the previous one.

    In some situations, that makes the predefined dashboard unnecessary.

    Sometimes the Right Answer Is “Show Me”

    Of course, not every answer is best expressed in words.

    Sometimes an explanation immediately creates a different need:

    Show me.

    Show me the sales trend.

    Show me where the customers are.

    Show me what changed.

    Show me how these components interact.

    Show me the evidence behind that conclusion.

    At that point, the system can create or retrieve a visualization appropriate to that particular question.

    The visualization still matters. What changes is that it no longer has to exist permanently because somebody once imagined it might be useful. It can be created at the moment it becomes useful.

    The same underlying information can also be consumed differently depending on the situation. Someone sitting at a desk may want a detailed written explanation. Someone preparing for a management meeting may want a few diagrams. Someone driving may simply want to talk. Someone investigating a difficult problem may move continuously between forms:

    Tell me what is happening.

    Why?

    Show me.

    Show me the evidence.

    Explain that part.

    The knowledge remains the same. The representation changes with the need.

    This suggests that documents, dashboards, reports, presentations and visualizations may increasingly become temporary views over more durable knowledge and data.

    The Command Prompt Returns

    There is an interesting historical irony here.

    The command line allowed users to tell computers what they wanted, but only if they knew how to speak the computer’s language. Commands, parameters, paths and syntax had to be learned.

    Graphical interfaces made computers easier to use by reversing the relationship. Instead of requiring users to know the command, the computer exposed possible actions through menus, buttons, forms, folders, dashboards and navigation structures.

    AI seems to bring us strangely close to the command prompt again. The user can once more simply express intent:

    How much did we sell today?

    What do we know about this customer?

    Why was this architecture chosen?

    What changed overnight?

    Show me the trend.

    The difference is that the command language is now ordinary human language.

    The user does not necessarily have to know which application contains the answer, which report to open, which dashboard to inspect or which sequence of operations will produce the result. The system can determine which sources, calculations and representations are required.

    The command prompt has returned. It just learned to speak human.

    When the System Asks for Our Attention

    There is another step beyond this. Sometimes the user should not have to ask at all. A dashboard assumes that somebody will look at it frequently enough to notice when something important changes. An intelligent agent can continuously interpret the underlying information instead.

    Rather than displaying a graph and waiting for a human to notice an undesirable trend, it can say:

    You may want to look at this.

    Or, less formally:

    Psst. You have a problem.

    The human can then ask why.

    The system explains.

    Show me.

    A visualization appears.

    What changed?

    The relevant history is retrieved and synthesized. The dashboard has not disappeared completely. It has become an on-demand representation inside a conversation. What used to be a permanent interface becomes something that materializes only when it helps us understand the situation.

    What Should Actually Be Permanent?

    This leads to a more fundamental question.

    What actually needs to be durable?

    We currently spend considerable effort maintaining representations. Documents have to be updated. Dashboards have to be redesigned. Reports have to remain current. Presentations are recreated. Diagrams gradually become obsolete. Interfaces are maintained because somebody may need to navigate through them in the future. Perhaps these are increasingly the wrong things to make permanent.

    What needs to remain durable is the material from which trustworthy representations can be produced: knowledge, data, evidence, sources, provenance, decisions, assumptions, relationships and expectations.

    Above that durable layer, representations can increasingly be generated according to the need of the moment. A document when a document is useful. A chart when a chart is useful. A spoken explanation when somebody wants to listen. A dashboard when somebody wants an overview. A detailed evidence trail when somebody wants to challenge a conclusion.

    The representation can be generated, consumed and discarded. The knowledge remains.

    The Death of the Predefined Representation?

    This does not mean that documents will disappear. Nor will dashboards, reports, presentations, diagrams or graphical interfaces. We may actually create more of them than ever.

    What may disappear is the assumption that these representations have to be designed, published and maintained before we know what somebody actually wants to know.

    Instead, the sequence becomes:

    Knowledge and data → Intent → Representation

    The representation is created at the moment of need, for the person who needs it, for the question they are actually asking and in the form most appropriate to the situation. Read it. Listen to it. Look at it. Interact with it. Then ask the next question.

    Perhaps the document was only the first thing we noticed becoming ephemeral. The more fundamental change may be the death of the predefined representation.