Documentation is organisational memory
Documentation is not written because people forget. It is written because organisations do.
A new feature exposed an unexpected problem.
Different customers used different codes and descriptions for the same business concept. During development, we needed to determine whether those differences were already represented somewhere in the product. It seemed like the kind of capability that should already exist. The difficulty was not understanding the business requirement, but finding enough evidence to trust that the solution was already there.
Unfortunately, the two colleagues who knew that part of the product were both on holiday. We searched previous tickets, the database and the available documentation, but none of them gave us enough confidence to conclude that the existing data model already supported the behaviour we needed.
Given the information available at the time, the safest decision was to extend the data model.
This was not a small implementation detail. Introducing a new column meant changing the structure of the system itself. Business analysis was completed, development began, the implementation was reviewed and testing followed. The team had already committed to a particular understanding of the problem.
A few days later, one of our colleagues returned.
The answer took less than a minute.
The column already existed.
We immediately withdrew the implementation.
Nothing had been implemented incorrectly. Based on everything we knew, the decision had been entirely reasonable. What changed was not the implementation, but our understanding of the system.
That experience changed the way I think about documentation.
The data already existed. The behaviour already existed. The organisation already possessed the necessary knowledge. What it lacked was a reliable way to discover and trust that knowledge.
Documentation is often described as something that explains software. I think its more important role is reducing uncertainty. Good documentation helps teams distinguish between two very different situations: we need to design something new, and we solved this problem years ago.
That distinction matters because uncertainty does not only slow decisions down. It changes the decisions themselves. When teams cannot confidently identify existing capabilities, they naturally begin designing new ones.
Good documentation is therefore not written for today’s project. It is written for the next person who needs to decide whether the organisation is facing a new problem or rediscovering an old solution.
It allows organisations to build with confidence instead of rediscovery.