Should I Document This?

November 27, 2022

Documentation - a frequently avoided topic among software developers, for whom natural language is not always their favorite kind of language - "If you want to know how it works, just look at the code". Theoretically perhaps correct, because how the application works is definitely in there. But practically not sufficient, because the why - the intention behind it, the underlying decisions and possible implications or discarded alternatives - cannot be found there.

If you consider how software documentation is usually created in everyday life, you can certainly understand why some developers keep it rather thin. (It should be mentioned that I’m talking about an agile development process in the broadest sense - extensive up-front documentation, dictated from the ivory tower and written down in stone tablets would not be something I would want to write about here). So now, as an agile developer, when I’ve built a new feature or done a major refactoring, I ask myself the question, “Should I document this change?”.

No doubt, this is not an easy question. Who can guess which (possibly future) stakeholders with which prior knowledge will read this documentation at what point in time and in which context? A serious answer to all these questions is unfortunately impossible. You will never be able to ensure in advance that you always document exactly the right thing and nothing beyond that. Somehow at least some developers have to answer the initial question, otherwise no documentation would exist for any project. But how do they arrive at this answer?

Decision making - made easy

It might help to look at the problem from a psychological perspective. I am firmly convinced that psychological heuristics take effect in a large number of cases. That means a difficult decision is unconsciously replaced with a simple one. In this case, the easier question might be something like “Do I feel like documenting this change right now?”. Unfortunately, that’s fatal because this question might be just as helpful as it is difficult to answer: not particularly.

So what can you do to stop this unconscious substitution? Personally, I try to be aware of the substitution and think of better simple questions to answer instead:

• “If I were new to the project, would I want to read about it?”
• “Would I have to explain the change to an inexperienced teammate?”
• “If I go on vacation now, would it be critical if no one on the team knew about it?”
• “When I (as a consultant) leave the project, should that knowledge be preserved?”
• “Do I think it’s likely that it would be important or useful to other teams?”

The list is not complete, but these are some of the questions I have asked myself in the past that have led me to document things. They also all have in common that there is always someone whose perspective to take - the audience for whom the documentation would then be intended. That not only makes the decision easier whether to write something, it also makes the writing itself easier because you have a good idea of who you’re actually writing for.

You can also read this article in german.