Today, I started off a series of documentation fallacies. Gerald M. Weinberg inspired this series. Since I didn’t have the initial inspiration quote handy at the time, I looked it up right now. As it is the initial one, I call it the documentation fallacy #0. It’s a citation from the reminders in Perfect Software… and other illusions about testing.

The Documentation Fallacy #0:

Believing that the mere existence of documents has some value.

Just because there is a document, means nothing. The document might just simply plainly lie around and start to get dusty. When no one is reading your document, then you have basically wasted all the time that you spent on preparing to write it, write it, review it, publish it. Period. Well, maybe you learned something as a side-effect, but you could have learned that one without writing a document that no one reads in first place. Ok, maybe you could have learned something by writing your thoughts down on the learning topic, sure, but still, the writing isn’t worth the paper that it is going to full. Save the rain-forest, remember?

So, just writing a document means nothing. It could be of no value because it has low quality, it could be of no value as it describes the life of Alfred E. Neumann, or it could be of no value as it describes how to the 8086 CPU was invented. If your project is not about any of these, you will simply not care about the content. More dramatically, your document could distract the people on your project and mislead. In the examples before I exaggerated to make a point, but what if the document was plainly wrong, and people started to work after it? Maybe you will end up with a project way behind schedule when you find out the problem right after delivery of the system. Doesn’t sound good, does it?

The Documentation Fallacy #1:
Thinking that more documentation means more thorough.

More documentation doesn’t mean anything. Personally, I find great value in those documents, that are as crisp as possible and point me out where to find the details if I need them. Usually I started to dig into a topic by getting a rough overview. After that I start to dig deeper and search for more details. This is the reason why to write requirements in a rough form before the work on the implementation begins. This concept can be found in use cases. Goals build the high level overview. There are different goal levels, and for more complicated business flows you write down an overview use case description alongside with finer-grained use cases on the subsystem or function level as you may see fit. Similarly when working on a user story, you start with a high-level overview and then start to dig deeper.

So, starting with a crisp overview is great. But when digging deeper you don’t need to document everything. The trivial cases are mostly irrelevant to document, because everyone already knows what shall be done in the login use case for example. Well, maybe you have a more complicated login use case, then document it, but if it, refuse to document the very obvious. Simplicity – the art of maximizing work not done – is the key here. But this does not mean that you shouldn’t document anything at all, of course. That would be stupid.

The Documentation Fallacy #2:
Thinking that since it’s documented, it gets read.

Just because it is written down somewhere, does not mean that anyone will read it. Maybe you’re lucky enough that someone reads it, but you can’t rely on it. Similarly you cannot rely on the fact that the people who actually need to read the document, have read it. Most of the time, documents simply lie around with no on reading them, covering dust – even virtually on the hard-drive of your computer. In the waterfall model we introduce the biggest problem here, since the documents don’t necessarily get read. I remember a case where we run into a problem during the user acceptance testing resulting from customer stakeholders not having read (properly?) the documents that we had sent them. Obviously this was the wrong time to find out that the software didn’t realize the functionality properly.

The Documentation Fallacy #3:
Thinking that since it gets read, it gets understood properly.

The Satir Interaction Model taught me, that not necessarily everything that gets read is understood in the same way for all readers of the document. The model splits up communication into four phases: intake, meaning, relevance, and response. During the intake each person takes in some parts of the message that she just heard. Therefore it gets distorted during the reception already. The meaning phase then interprets the message based on the personal rule model and previous knowledge of the receiver. This might distort the message even further. Overall, this may result in necessary details left out, or unnecessary details added to that message.

That said, it’s obvious that everyone may understand something different when reading a particular document. As the message and the meaning are distorted from what the receiver takes in (partially) and what she adds to the message based on previous experience, the understanding may well end up as being something completely different. So, just barely reading a document does not mean that the author’s intentions were understood.

The Documentation Fallacy #4:
Thinking that since it gets read, it actually gets used downstream.

Thanks for Paul Boos, who added this to my initial list. The two parts from the Satir Interaction Model left out of the discussion so far are the relevance and the response parts. On the relevance I assign to the distorted message how important I think that interpreted message is to me. If it is irrelevant, I might end up ignoring the message overall, thinking “fine, so what?”, or “don’t bother me.” I might also end up giving the relevance to completely ignore the message without responding to it. In the response I can decide how to react to me interpreted message, that I assigned some relevance. I can say something completely different, even out of context, like “nice weather outside, isn’t it?” This means that the mere existence of a document does not mean that I will follow it’s contents when reading it. It’s important what relevance I assign to the message and how I decide to respond to that message.

The Documentation Fallacy #5:
Thinking that since it is understood properly, it is used properly

Thanks for Jeroen Rosink for this addition. As derived from the Satir Interaction Model again, the response I take to my understanding of the document may vary to a great deal. This means that I might understand the document, but this does not necessarily mean that I will apply the message accordingly. In fact, most of the software I crossed was used unintentionally, in different ways, that the developers initially did not intent. The Windows scripting capabilities are one example of this coincidence, but there are many, many other examples out there. I’m sure you can name at least five on your own.

Please let me know of any additions I could make to that list. Hopefully, I raised some of your thoughts by now, so share your stories on misused or unread documentation with me.