Communication and documentation
It is common that after a tricky bug has been fixed, a development team or someone in their surroundings comes up with the idea to “document more”. If we had only documented exactly the explanation that would have prevented the confusion that caused this issue, it would never have occurred! Of course, this is easy in hindsight, but hindsight is not very useful in preventing problems. Can we know what to document before issues arise? In this post, I will explore why documenting well is challenging, and offer strategies to do it effectively without taking all of your time.
In order to understand documentation, we must understand communication. And to understand communication, we must understand information. It goes without saying that information is a core concept in Information Technology. Literature defines it as data structured with a goal or meaning1. A related concept, knowledge, is subtly different: internalized information that can be used to make decisions.
Where information is (mostly) objective, knowledge is created within the mind, and will be different for each different mind. For example, the same weather forecast of 20ºC and sunny will mean different things to people from different climates: a Dutch person like myself might leave their coat at home, while an Italian will definitely bring a jacket. The same information leads to different decisions based on existing knowledge. This knowledge can be obtained by place of birth, but also by career, age, environment, and many other factors.
Communication is the exchange of information. This poses a fundamental challenge: it is not the direct exchange of knowledge. Rather, if we want to share our knowledge, we have to craft a piece of information from it and communicate it to the receiver, who will then interpret that information with their own brain to build new knowledge from it. Even worse, if we want to find out if our communication had the desired effect, the receiver has to form a piece of information that describes their knowledge and communicate it back to us.
Communication exists in many different forms: verbal or written, one-to-one or one-to-many, synchronous or asynchronous. Each form has its pros and cons. A form that often has preference when describing software is written, one-to-many and asynchronous. Filling wiki pages that can be referenced at a later point by others to understand how things work and why. This asynchronous, written, one-to-many communication is what we call documentation. Although the rationale for this form of communication is legitimate, it is also the version where different understandings can occur without either the sender or the receiver noticing immediately (due to the asynchronous nature).
Generally, everyone agrees that documentation on the system needs to exist. Venturing into a system without any documentation means you will have to figure out from the controls and code what it does. And while code is unambiguous, it is not always obvious how it behaves2.
But what do we document, and at which level? We cannot document everything in every possible way, as (1) the time taken documenting will eat up the time that could be spent on development, and (2) an enormous body of documentation actually makes it harder to find the answers you are looking for. We want the smallest possible amount of documentation that can answer the largest amount of questions, in a way that can be updated easily. On top of this, it should be interpretable for all stakeholders in the right way without additional explanation.
This all may sound familiar: the challenges we have for documentation are very similar to the ones we have for code. We don’t know how readers will respond to documentation, we don’t know exactly what they need beforehand, and we don’t know if the documentation structure we have now will be the best one in the future as well. Luckily, this means we can also reuse some techniques to tackle the documentation challenge. I will share three strategies that I use to document less while explaining more.
1. Write for the reader (and their needs)
You cannot help everyone with everything in your documentation, but you can try to figure out who reads it for what reason. If you’re documenting an application for users, explain in plain language what they can do with the application. When writing for developers, answer questions that are not obvious from the code. The code is a good source for developers to look at, and documenting something that the code already explains very well is just duplicate work. Of course, judging what is obvious for developers is best judged by those same developers.
2. Invest in a steady base
The system that is the subject of documentation may be under active development, but the foundation should be relatively steady. If this is the case, make sure to document that carefully. Understanding the base on which your subject was built will allow for easier understanding of your reasoning. From my expertise as a business analyst, a good domain model that captures relationships between domain objects is very helpful in getting people to understand the topic that the system covers. It allows domain experts and developers to reason together about what the subject of your system really is. Technology, documenting the solution architecture (for example using the C4 model) or using Architectural Decision Records can quickly give developers an understanding of how the solution was set up.
3. Step back and reconsider periodically
When creating something over a longer period of time, it is easy to get lost in the day-to-day work and forget the bigger picture. Just like systems and applications, take some time every so often to consider what purposes your documentation is serving and whether all of it is still required for that purpose. Do not be afraid to prune and remove docs that are no longer important or that could be written down more effectively. The challenge is to keep it simple, as explained in my post on Deliberate Simplicity.
Those working in software development will see that these strategies for documentation are also good practices for creating software. This parallel is logical: the documentation of a system is an artifact just like the system itself, and it is subject to the same lifecycle. It would be great if we could know the best way to structure documentation up front, but we simply do not: we can only do the best possible job given what we know right now.
Besides these strategies, it is important to realize that understanding can be achieved in multiple ways, so do not treat documentation as the holy grail. Understanding can be validated best by triangulation: gaining evidence from different sources. A voice-over to answer the questions that documentation raises can make a big difference. The route to ‘perfect’ documentation is long and not worth the cost of travel, but having no documentation at all will lead to more confusion in the future. Documentation is information that helps build knowledge, but do not fall into the trap of believing that having good documentation alone is enough.
Ultimately, the goal of documentation should not be to cover every possible detail but to create a balance between clarity and practicality. Use the strategies—focusing on the reader, documenting the steady base, and reassessing regularly—to create documentation that is both useful and manageable, ensuring that your team stays productive without falling into the documentation trap.
Zins, C. (2007). Conceptual approaches for defining data, information, and knowledge. Journal of the American society for information science and technology, 58(4), 479-493.
Evans, E. (2004). Domain-driven design: tackling complexity in the heart of software. Addison-Wesley Professional.