Marcel van Oosterwijk

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 Why of System Documentation

    Documentation has a reputation problem. Ask software engineers how they feel about documentation and many will describe it as something they have to do rather than something they want to do. Documentation is often incomplete, outdated or ignored. It is frequently treated as a deliverable rather than an asset. Perhaps that is because we have forgotten why documentation exists.

    A while ago, I worked with a CTO who openly disliked system documentation. His preferred solution was different: everyone should work on everything. If every developer understood every part of the system, knowledge could not become concentrated in a few individuals.

    I understood the concern. When critical knowledge exists only inside a handful of people’s heads, every resignation, holiday or illness becomes a business risk. But the proposed solution never convinced me. t always felt like the wrong solution to the right problem.

    Making everybody know everything may work for a small team and a small product. As organizations and systems grow, however, it becomes increasingly unrealistic. Complexity grows faster than any individual’s ability to understand it all. Perhaps the answer is not to make every person know every system. Perhaps the answer is to make every system preserve enough of its own meaning that future people can reconstruct why it is the way it is.

    That leads to a different question:

    What is documentation actually for?

    We often think documentation describes a system. It doesn’t.

    The source code already describes the implementation. Configuration files describe the environment. Databases describe the data. APIs describe the interfaces. If documentation merely repeats information that already exists elsewhere, it quickly becomes redundant—and eventually outdated.

    The real purpose of documentation is different. Documentation exists to preserve meaning. Future developers can usually discover what a system does. What they cannot easily reconstruct is why. Why does this system exist? Why was this architecture chosen? Why was this dependency accepted? Why is this apparently strange business rule still enforced? Why was this workaround considered preferable to fixing the underlying problem? Those answers rarely exist in the code itself.

    When the people who understood those decisions leave, the implementation remains. The system continues to run. But the understanding slowly disappears. Maintenance then becomes archaeology. Every unusual piece of code raises the same question: Was this deliberate, or simply forgotten?

    This is where documentation earns its place. Not by attempting to explain everything. Not by describing every class or every method. But by preserving the things that future people cannot easily rediscover for themselves. The assumptions. The trade-offs. The decisions. The stories. The reasons.

    Documentation should preserve enough context that future people can reconstruct the original meaning. Perhaps that is the real why of system documentation. Not to describe the system. But to ensure that understanding survives the people who created it.

    Because continuity is not achieved when everybody knows everything. Continuity is achieved when the next person does not have to start from zero.

  • Practice Note: The Paragraph Is the Unit of Thought

    Writing is often reviewed one sentence at a time. Is the grammar correct? Is the wording clear? Is the sentence too long? Could a stronger verb be used?

    These are useful questions, but they may focus attention on the wrong unit. A sentence can be perfectly written while the paragraph around it remains confused. Several individually strong sentences do not necessarily form a coherent argument.

    I increasingly suspect that the paragraph, rather than the sentence, is the fundamental unit of expository writing. A sentence carries a statement. A paragraph carries a thought.

    I first learned to recognize this structure through summarization. To summarize a text, I was taught to examine each paragraph and identify its main statement. That statement was often found at the beginning or the end. The remaining sentences provided explanation, examples, qualifications or supporting detail. Remove that elaboration, and the central message of the paragraph remains.

    Writing can be understood as the reverse operation. Begin with a governing statement. Then develop it through explanation, evidence, examples or consequences. Sometimes the paragraph opens with the key idea and explores it. Sometimes it begins with an observation or example and only reveals its conclusion at the end. In either case, the sentences belong together because they perform different roles within the same thought.

    This became especially visible while editing text produced through conversations with AI. AI can generate convincing sentences very quickly. It also tends to give important statements dramatic isolation, placing each one in a separate paragraph. Used occasionally, that can create emphasis. Used repeatedly, it produces a staccato rhythm in which every sentence appears to demand attention. The result may resemble a speech or a social-media post more than a reflective essay.

    I found myself gathering those isolated sentences into more substantial paragraphs. I identified the key statement and placed the relevant explanations and examples around it. Short sentences could still provide emphasis, but they now concluded or punctuated a developed thought rather than standing alone by default.

    At first, I considered this an editorial preference. It gradually became clear that I was doing something more important. Regrouping the sentences forced me to understand them.

    I could not merely read through a proposed draft and accept that it sounded plausible. I had to decide which idea governed each paragraph, which sentences supported it and where the thought reached its natural conclusion. If two sentences could not comfortably share a paragraph, I had to ask whether they really belonged to the same argument. Paragraphing became a reviewing technique.

    This suggests a simple way to test a piece of writing: summarize every paragraph in one sentence. If the governing thought is difficult to identify, the paragraph may contain several competing ideas—or none that has been developed clearly enough. If several consecutive paragraphs produce essentially the same summary, the text may be repeating itself.

    The reverse test is equally useful. Once the governing statement has been identified, ask whether the rest of the paragraph genuinely helps the reader understand it. Elaboration should develop the thought, not merely lengthen the text.

    This applies beyond AI-assisted writing. A report, essay or paper may contain accurate statements yet remain difficult to follow because the reader cannot see how they form coherent units of reasoning. Good paragraph structure gives the argument shape. Each paragraph makes one contribution and prepares the transition to the next.

    Perhaps this is why paragraphing should not be treated as formatting. It is part of thinking.

    A sentence carries a statement. A paragraph carries a thought.

    The sentence may be the smallest unit we write. But the paragraph may be the smallest unit through which we genuinely explain.

  • Practice Note: System Continuity

    Systems fail when continuity is broken. When we think about continuity, we usually think in technical terms: backups, version control, redundancy or disaster recovery. Those preserve systems.

    But there is another kind of continuity that is just as important:

    The continuity of understanding.

    A few years ago, after my father passed away, I inherited many of his belongings. Some objects immediately meant something to me. His field glasses, for example, reminded me of my childhood. They carried a story, and because of that story they retained their meaning.

    Many other objects did not. They may have been just as important to him, but I simply didn’t know why. Without their stories, they became little more than anonymous possessions. The objects survived. Their context did not.

    Software systems suffer from exactly the same problem. Production systems often survive for decades. The source code is still there. The database still exists. Diagrams, tickets and documentation may still be available. Yet the people who understood why the system was designed that way have long since moved on.

    A peculiar integration remains, but nobody remembers which dependency required it. A workaround survives, but the incident that justified it has been forgotten. A business rule is still enforced, but nobody knows why it was introduced. The system survives. Its context does not.

    The next generation inherits the equivalent of a room full of possessions: many artifacts, some clearly important, others seemingly meaningless, with very little explanation of the stories that connect them.

    Without those stories, maintenance becomes archaeology. Changes become risky because nobody can distinguish deliberate design from historical accident.

    That experience has changed the way I think about documentation. Documentation does not preserve knowledge. At best, it preserves information. Knowledge survives only when enough context is preserved for future people to reconstruct the original meaning.

    Knowledge is not preserved by storing documents. Knowledge is preserved by maintaining enough context that future people can reconstruct the original meaning.

    That context rarely consists of technical details alone. Sometimes it is the problem that triggered an idea. Sometimes it is the trade-off that was consciously accepted. Sometimes it is a story. Sometimes it is simply the answer to a single question:

    Why?

    Perhaps that is the real purpose of documentation. Not to describe every detail. But to preserve enough understanding that the next person can continue the story instead of starting over.

  • Practice Note: Continuity

    A few months ago, my mother passed away. Recently, a question about our family history popped into my head. My immediate reaction was simple: I’ll ask Mom. Then I remembered, I couldn’t. The answer disappeared with her.

    A Library of One

    What struck me was not the loss itself. I had already experienced that. What struck me was the realization that my mother had carried a unique body of knowledge. Stories. Relationships. Explanations. Family history. Context. The answers to questions nobody knew would one day be asked. For years, that knowledge was always available. A simple question was enough.

    Then suddenly it wasn’t. Not because the knowledge lacked value. Because the person who carried it was no longer there.

    The Fragility of Knowledge

    This is not unique to families. Every person carries a library. Years of experience. Lessons learned. Mistakes made. Patterns observed. Insights developed.

    Much of this knowledge exists nowhere else. It remains tacit. Unwritten. Unrecorded. Accessible only through conversation. When a person leaves, part of that library often disappears as well.

    Thinking About My Own Library

    The experience made me reflect on my own situation. Over the course of a career, I have accumulated a large collection of observations, mental models, and insights. Some are personal. Some are professional. Some are useful only to my family. Others may be useful to people I will never meet.

    Like everyone else, I will eventually leave this world. The question is not whether that happens. The question is what happens to the knowledge I carry when it does.

    Two Different Forms of Continuity

    I find myself thinking about continuity in two different ways.

    The first is personal. I would like my son to have access to as much of my experience as possible. Not because I expect him to follow the same path. But because every parent hopes to pass on some of what they have learned.

    The second is broader. I would like useful ideas, observations, and lessons learned to remain available to others. Not because they are mine. But because they might help someone else think, learn, or solve a problem.

    Why Field Notes Matter

    For years, capturing knowledge required significant effort. Books had to be written. Articles had to be published. Most insights never made the journey from intuition to publication.

    Today, the friction is much lower. A thought can become a conversation. A conversation can become a field note. A field note can become part of a growing body of knowledge. Each note is a small act of continuity. A small attempt to ensure that something learned does not simply disappear.

    Beyond Immortality

    People sometimes speak about legacy or immortality. I find myself less interested in those ideas.

    The opposite of mortality is not immortality. It is continuity. I do not need my name to survive. What I hope survives are the useful things. The lessons. The observations. The insights. The things that might still help someone after I am gone.

    A Working Hypothesis

    This leads me to a simple hypothesis:

    Human lives are finite. Continuity is not.

    Every conversation, story, lesson, article, field note, and book is an attempt to carry something forward. Not forever. But long enough to matter.

    Perhaps that is one of the most meaningful things we can do with the knowledge we accumulate during a lifetime.

    Not keep it. Pass it on.

  • Practice Note: Uncovering Hidden Ideas

    When people discuss AI-assisted writing, the conversation often focuses on productivity. Writing becomes faster. Editing becomes easier. Publishing becomes cheaper. While all of this is true, I increasingly believe it misses the most important effect. The greatest value of reduced friction is not efficiency.

    It is revelation.

    The Myth of Fully Formed Ideas

    We often imagine that ideas already exist inside our heads. The challenge is simply expressing them clearly. In this view, writing is a transmission process. An existing thought is transferred from mind to paper.

    My experience suggests something different. Many valuable ideas do not exist in a fully formed state. They begin as vague intuitions. Patterns. Questions. Half-recognized connections. At this stage, the idea is not ready to be written. In many cases, it is not even ready to be articulated.

    Ideas Need Space to Develop

    For an idea to mature, it must be explored. Questions need to be asked. Assumptions need to be challenged. Alternative interpretations need to be considered. Connections need to be discovered.

    Historically, this process carried significant friction. As a result, many ideas never progressed beyond an initial intuition. Not because they lacked value. But because they never received enough attention to become visible.

    Hidden Rather Than Lost

    Looking back, I suspect that many of our best ideas are not lost. They remain hidden. They exist as possibilities rather than conclusions. As intuitions rather than models. As observations rather than theories.

    The problem is not that we fail to generate ideas. The problem is that most ideas never receive enough exploration to reveal what they might become.

    What Changes When Friction Disappears

    When the effort required to explore an idea becomes negligible, something remarkable happens. Ideas can be followed immediately. Questions can be pursued. Connections can be tested. Hypotheses can be challenged. Thoughts that would previously have remained unfinished can evolve.

    The result is not merely more writing. The result is the emergence of ideas that would otherwise have remained hidden.

    A Working Hypothesis

    This leads me to a hypothesis:

    Lower friction does not simply make it easier to express ideas. It makes it easier to discover them.

    The most valuable outcome is not faster publication. It is the revelation of thoughts that would never have become fully visible without the opportunity to explore them.

    Perhaps the greatest contribution of AI is not that it helps us write what we already know. Perhaps it helps us discover what we think.