Category: Field Notes

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.

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.

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.

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.

If I were to organize a conventional comparison between my Apple Watch and my Victorinox I.N.O.X. Automatic, the outcome should be predictable. The Apple Watch tells time more accurately. It adjusts itself when daylight saving time begins and when I enter another time zone. Its display is larger, brighter and, depending on the chosen watch face, easier to read under varying lighting conditions. The amount and presentation of information can be adapted to my needs.

It also does considerably more than tell time. It displays notifications, tracks exercise, monitors aspects of my health, provides navigation, controls music, manages timers and connects me to the rest of my digital life. In many situations, it could even replace my smartphone, although I have never really used it that way.

The Apple Watch is also exceptionally easy to reconfigure. Its strap system makes changing from a sports band to a leather strap or metal bracelet almost effortless. The watch face can then be changed just as quickly, altering the information, colors and graphical character of the watch.

The Victorinox mainly tells the time—and does so less accurately. It must be adjusted manually. Its dial cannot be changed, its functionality cannot be extended and its mechanical movement will eventually require maintenance.

Victorinox is moving in the same direction with its tool-free straps. Changing between the steel bracelet and leather straps on my I.N.O.X. is now quick enough to make the watch feel like a small system of configurations rather than one fixed object. Even so, Apple’s solution remains more immediate, and its combination of physical and digital configurability is much broader.

By almost every obvious functional and practical criterion, the Apple Watch is the better watch. Yet the Victorinox is currently the one on my wrist. Perhaps that means the comparison is measuring the wrong thing.

What job does a watch perform?

A watch is an instrument for telling time, but accurate time is now available almost everywhere. It appears on phones, computers, cars, appliances and public displays. Wearing a watch is no longer necessary in the way it once was.

That means a watch can perform another function. For many men, including me, the wrist is one of the few places where wearing an object partly for its beauty, materials and character is entirely unremarkable. A watch can function as jewelry without looking like conventional jewelry.

Calling the Victorinox jewelry does not dismiss its engineering or practical purpose. It recognizes that considerable effort has been spent on making the physical object worth wearing. Its faceted steel case, textured dial, applied markers, hands, finishing and mechanical movement are not merely packaging around its timekeeping function. They are an important part of what the product is for.

The movement inside captures the contradiction particularly well. It is sophisticated machinery, produced through advanced engineering and manufacturing, that performs an archaic function with limited accuracy. From a purely functional perspective, much of its complexity is unnecessary. Yet that unnecessary complexity contributes to my fascination with the object.

The Apple Watch performs a different role. It is primarily a small computer and an extension of the smartphone. Its design is recognizably Apple: pragmatic, coherent, restrained and carefully resolved. It is extremely good at presenting information and supporting interaction.

Yet I find it less captivating as a physical object. The Apple Watch offers a seemingly endless selection of watch faces. Their colors, complications, typography and information density can change instantly. But every face remains an image displayed on the same flat screen.

The I.N.O.X. offers no such variety. It has one dial, one set of hands and one permanent arrangement of physical elements. But those elements possess depth. The applied markers cast shadows. Polished and brushed surfaces respond differently as the light changes. The hands move physically above a textured dial rather than being rendered onto it.

The Apple Watch is designed to make information easy to see. The Victorinox is designed to make the object rewarding to look at. That is a different quality.

The hidden reference model

The Apple Watch wins when I compare the two watches on accuracy, functionality, clarity, adaptability and ease of configuration. The Victorinox wins when I compare them on physical presence, material character, craftsmanship, visual depth and the pleasure I experience from wearing the object. Neither comparison is dishonest. Each follows from a different set of criteria.

The criteria together form what could be called a reference model: a description of the qualities against which the product is judged. Change the reference model, and the outcome of the assessment may change with it.

Apple understandably promotes the criteria on which the Apple Watch is strongest. Its story is largely about capability: what the watch can measure, display, communicate and automate. Even personalization is presented mainly through selectable faces, configurable complications and interchangeable straps.

Those are all legitimate forms of value. But they may not be the qualities that ultimately decide which object I place on my wrist.

The Apple Watch is not competing only for the role of personal digital assistant or timekeeping instrument. It occupies a place on the body that has historically also been used for craftsmanship, decoration, identity and personal expression.

That creates a contest Apple cannot necessarily win by adding another function. The Apple Watch may be the better device. The I.N.O.X. may still be the better object for me to wear.

Functionality is not the whole product

This comparison also exposes a familiar risk in software development. Most software teams now work incrementally. Rather than attempting to build a complete and fixed product all at once, they develop it in smaller steps, learn from its use and adjust their priorities as new information becomes available.

This is often associated with the idea of a Minimum Viable Product, or MVP. An MVP is the smallest usable version of a product that allows a team to test whether it addresses a real need and to learn what should be developed next.

In practice, however, minimum can easily become interpreted as the smallest collection of functionality that works. That interpretation encourages a narrow question:

What must the product do?

The question matters, but it is not sufficient.

Both of my watches tell the time. If that were the complete requirement, both would qualify. Even when accuracy, clarity and adjustability are included, the Apple Watch would win decisively. Yet those criteria do not explain my choice.

Products also possess qualities surrounding their functionality. How reliable are they? How easy are they to understand and adjust? How readable are they? How do they respond under different conditions? How maintainable are they? How much trust do they create? Do people enjoy interacting with them? Do they want to keep them?

Some of these qualities are conventionally described as non-functional requirements or quality characteristics. That name can unfortunately make them sound secondary, as though functionality defines the real product while everything else merely improves it.

But the watch comparison suggests something different. The quality of telling time includes accuracy, clarity, readability and ease of adjustment. The quality of wearing a watch may also include comfort, materials, visual depth, identity, craftsmanship and attachment. These are not additional functions, but they may determine whether the product succeeds in the place it was created to occupy.

A Product Owner who concentrates only on functionality may therefore optimize an incomplete reference model. The team may deliver everything the product was asked to do while overlooking what kind of product people actually want to use, trust, keep or identify with.

Product Ownership should not be limited to managing a list of capabilities. It should help preserve an understanding of the complete product: its purpose, its intended users, its operating context and the qualities through which it is expected to create value.

The question is not only whether the product tells time. It is also what kind of experience telling time should become.

Losing my wrist

None of this makes the Victorinox the objectively better watch. Many people would choose the Apple Watch, and for perfectly sound reasons. They may value its accuracy, clarity, adaptability, health functions and integration with the rest of their digital lives. They may also prefer its restrained design to the large, industrial presence of the I.N.O.X.

Not everyone will find a mechanical movement fascinating. What I experience as intricate machinery and physical character may appear to someone else as unnecessary complexity wrapped around an outdated method of telling time.

Nor will everyone like the I.N.O.X. It is substantial, heavy and visually assertive. Those are important parts of its appeal to me, but they may be precisely the reasons someone else rejects it. The comparison therefore does not reveal which watch everyone should choose. It reveals which criteria currently matter most to me.

By almost every measurable and utilitarian standard, the Apple Watch is the stronger product. It is more accurate, more capable, easier to read under different conditions and easier to reconfigure. Yet when I decide what I want to wear, physical presence, material depth, permanence and attachment carry more weight than that comparison acknowledges.

The functional criteria are not wrong. They are simply incomplete for the decision I am actually making. The Apple Watch may be the better watch. For me, the I.N.O.X. is currently the better object to wear.

The better watch does not lose universally. It loses my wrist—because I’m not choosing only a watch.