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.
Leave a Reply