Category: Knowledge & AI

How knowledge and understanding are created, represented, preserved, synthesized, transferred, and developed, including the changing role of AI in knowledge work.

  • Practice Note: The Story Behind the Facts

    For years I tried to make my reports correct. Then I tried to make them complete. Eventually, I realized I wanted something else: I wanted them to be skön att läsa—enjoyable to read. At first, that sounded almost inappropriate. A report is supposed to be factual, objective and complete. It isn’t supposed to compete with a novel. Or is it?

    Looking back over years of writing reports and giving presentations, I noticed a pattern. Of the many presentations I have delivered, those that received the strongest engagement were rarely the ones in which I tried hardest to explain every fact. They were the ones in which I unintentionally told a story. Not fiction. A real story.

    Those presentations felt different. I was more relaxed. I wasn’t constantly wondering whether I had forgotten a fact or whether someone would misunderstand a definition. I simply invited the audience to walk the same path that had led me to the insight. The audience seemed to enjoy that journey as much as I did.

    Only recently did I realize that the same principle applies to writing. Many technical reports feel like collections of facts. Everything is correct. Everything is complete. Yet reading them feels like climbing a staircase while carrying boxes. Every page asks the reader to do more work. What if the facts themselves are not the problem? What if the problem is that they have no journey to travel on?

    The reader keeps asking:

    “Why are you telling me this?”

    A story answers that question naturally.

    Ironically, storytelling may be one of the most effective ways to communicate technical ideas. Not because it simplifies them. But because it makes understanding feel effortless. A story does not replace facts. It gives the facts somewhere to live.

    Yet storytelling and style are often treated as luxuries for which professional work has no time.

    “Don’t waste my time. Just give me the facts.”

    But facts without a story do not eliminate the work of creating meaning. They merely leave that work to the reader. Making a report skön att läsa takes time. Framing a presentation as a story takes time.

    So does trying to understand a report whose writer decided that readability was a luxury.

    So does trying to make sense of a presentation that is merely a wall of facts.

  • Practice Note: Pluribus and the Preservation of Knowledge

    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.

  • Practice Note: Recording the Answers

    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.

  • Practice Note: Can AI Recover the Why?

    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.

  • Practice Note: Understanding Debt

    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.