Category: Practice Notes

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.

I should begin with a confession: I have been an Apple fan for a very long time. My attachment became particularly strong after Apple acquired NeXT and Steve Jobs returned to the company. I did not merely admire the products that followed. I believed in the why behind them: the conviction that technology should become understandable, personal and humane through the careful integration of hardware, software and design.

Over the years, Macs, iPods and iPhones became natural parts of my life. Each product seemed to extend the same philosophy into another area. When Apple introduced the Apple Watch, putting one on my wrist therefore felt almost inevitable. It was not merely another device. It was the next extension of an ecosystem—and an idea—I had already followed for years.

For more than a decade, the Apple Watch seemed to make a traditional watch difficult to justify. It could tell the time while also displaying messages, tracking exercise, monitoring health, navigating and connecting me to the rest of my digital life. A mechanical watch, by comparison, appeared almost absurdly limited.

Then I bought a Victorinox I.N.O.X. Automatic. It is a substantial hunk of metal containing an elaborate mechanical movement whose main purpose is to tell the time less accurately than the computer on my wrist. It cannot display a notification, install an application or acquire a new capability through an update. In technological terms, it was already an anachronism when it left the factory. Yet it gradually became the watch I wore all the time.

The two watches may occupy the same place on the body, but they perform fundamentally different roles.

The Victorinox is partly an instrument for telling time, but it is also jewelry—not in the sense of superficial decoration, but as an object whose materials, architecture and manufacture are central to its reason for existing. Considerable effort has gone into the faceted steel case, the textured dial, the applied markers, the hands, the finishing and the mechanical machinery inside.

That machinery is both advanced and archaic. It depends on sophisticated engineering and precise manufacturing to perform a function that electronics solved more accurately decades ago. Its limited functionality is not a flaw awaiting correction. It is part of the object’s identity.

The Apple Watch is something else. It is a wearable computer and an extension of the smartphone. In many situations, it could even replace the phone, although I have never really used it that way. For me, it remains a convenient interface to the larger digital system around it: useful, responsive and deeply integrated, but not entirely independent.

Its design is unmistakably Apple—pragmatic, coherent and carefully resolved. Yet I find it less captivating as a physical object. There is a seemingly endless choice of watch faces, but every one of them appears on the same flat screen. Colors, complications and graphic styles can change instantly, while the underlying object remains visually much the same.

The Victorinox offers almost no such variety. It has one dial, one set of hands and one composition of physical elements. But those elements possess depth. Applied markers cast shadows. Polished and brushed surfaces respond differently to changing light. The hands move above a textured dial rather than being rendered onto it.

Perhaps that is the distinction:

The Apple Watch can display countless faces. The Victorinox has a face.

One offers visual variation through software. The other offers a single physical composition that can continue revealing details through observation.

The two watches also live on different timescales.

An Apple Watch lives on the timescale of software. Its value can increase through new releases, new services and new capabilities. The hardware may remain unchanged while an update substantially changes what the watch can do. At the same time, continued progress eventually leaves older devices behind. A watch may still perform everything it did when it was purchased, yet gradually become outdated because the surrounding platform continues to evolve.

My Apple Watch Series 8 illustrates that tension. It remains capable, but it will no longer receive (major) software updates. My Apple Watch Ultra 3 will eventually face the same reality, even if that moment is still, hopefully, years away.

The Victorinox lives on another timescale. Its capabilities were effectively complete when it left the factory. It will not become more useful next year, but neither does it depend on a changing software platform to remain relevant. It may require maintenance, and its mechanical parts will eventually need attention, but its fundamental purpose will not become incompatible with a new operating system. Its limitations are stable.

Paradoxically, those limitations help protect it from obsolescence. Because it promises so little, technological progress has fewer opportunities to leave it behind. It can instead acquire scratches, memories and associations while remaining recognizably the same object.

At the moment, the Victorinox is winning. It offers physical depth, mechanical presence and the feeling of wearing an object that is already complete. It earns its place through what it is.

But the outcome is not permanent. The Apple Watch competes through usefulness, and usefulness can change suddenly. A genuinely capable assistant on the wrist, more meaningful health functions or greater independence from the phone could make it compelling again.

The next important Apple Watch generation may not even require new hardware. It could arrive as software, transforming the Ultra I already own into something substantially more useful. The same physical watch might suddenly earn its place on my wrist again because of what it has become capable of doing.

That reveals two different value systems. The Victorinox does not need to improve to remain relevant. Its value lies in permanence, craftsmanship, presence and attachment. The Apple Watch must continue to evolve. Its value lies in what current technology allows it to do—and in what the same hardware may still become through software.

One wrist becomes the meeting place of those two systems: timelessness and usefulness, permanence and progress, completion and continuous development.

Neither side wins forever. For now, I prefer the object that no longer needs to become anything else. Tomorrow, a software update may tilt the balance.

The I.N.O.X. wins through what it is. The Apple Watch may win through what it becomes.

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.

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.