Developers work with code and, since we have established that code is the most accurate documentation, there is no reason to not utilize it. If you want to understand what some method does, take a look at the code of that method. In doubt about what some class does? Take a look at that class. Having trouble understanding a piece of code? We have a problem! However, the problem is not that the documentation is missing, but that the code itself is not written well.

Looking at the code to understand the code is still often not enough. Even though you might understand what the code does, the purpose of that code might not be so obvious. Why was it written in the first place?

That's where specifications come in. Not only are we using them to continuously validate the code, but they also act as executable documentation. They are always up to date because if they aren't, their execution will fail. At the same time, while code itself should be written in a way that is easy to read and understand, specifications provide a much easier and faster way to understand the reasons, logic, and motivations that lead us to write some piece of implementation code.

Using code as documentation does not exclude other types. Quite the contrary, the key is not to avoid using static documentation, but to avoid duplication. When code provides the necessary details, use it before anything else. In most cases, this leaves us with higher-level documentation, such as an overview, the general purpose of the system, the technologies used, the environment set-up, the installation, building, and packaging, and other types of data that tend to serve more like guidelines and quick-start information than detailed information. For those cases, a simple README in markdown format (http://whatismarkdown.com/) tends to be the best.

For all code-based documentation, TDD is the best enabler. Until now, we worked only with units (methods). We are yet to see how to apply TDD on a higher-level, such as, for example, functional specifications. However, before we get there, let's speak about other roles in the team.