In many of the organizations that we worked with, the documentation was created for the wrong reasons. The management tends to think that documentation is somehow related to project success—that without a lot of (often short-lived) documentation, the project will fail. Thus, we are asked to spend a lot of time planning, answering questions, and filling in questionnaires that are often designed not to help the project but to provide an illusion that everything is under control. Someone's existence is often justified with documentation (the result of my work is this document). It also serves as a reassurance that everything is going as planned (there is an Excel sheet that states that we are on schedule). However, by far the most common reason for the creation of documentation is a process that simply states that certain documents need to be created. We might question the value of those documents, however, since the process is sacred, they need to be produced.

Not only might that documentation be created for the wrong reasons and not provide enough value, but, as is often the case, it might also do a lot of damage. If we created the documentation, it is natural that we trust it. However, what happens if that documentation is not up to date? The requirements are changing, bugs are getting fixed, new functionalities are being developed, and some are being removed. If given enough time, all traditional documentation becomes obsolete. The sheer task of updating documentation with every change we make to the code is so big and complex that, sooner or later, we must face the fact that static documents do not reflect the reality. If we are putting our trust into something that is not accurate, our development is based on wrong assumptions.

The only accurate documentation is our code. The code is what we develop, what we deploy, and is the only source that truthfully represents our application. However, code is not readable by everyone involved with the project. Besides coders, we might work with managers, testers, business people, end users, and so on.

In search of a better way to define what would constitute better documentation, let us explore a bit further into who the potential documentation consumers are. For the sake of simplicity, we'll divide them into coders (those capable of reading and understanding code) and non-coders (everyone else).