This is misunderstood to mean that agile projects do not have documentation. Discussions about agile often revolve around this point, and statements of the form "Agile says no documentation, so lets stop documenting and we'll be agile" are heard once in a while. At the other end is the "Agile says no documentation, so it's just ad-hoc coding" camp.
Working software over comprehensive documentation
Agile processes are not about eliminating documents. Agile processes are about delivering working software. The line in the manifesto is a reference to waterfall processes.
A traditional waterfall project has phases: Requirements, Analysis, Design, Coding, Integration, Testing. For the sake of example, lets say that each phase takes a month to complete, so the whole project time is six months. Three months into the project, we have delivered the requirement spec and design documents, but no software. By the fourth stage we have some software but it's not integrated and hence unusable at this point. Only at the end of the sixth stage — the end of project — do we get any working software. In the meantime we have delivered lots of documents, but no software. Agile projects should deliver software right from the start instead of delivering only documents for five out of six months. That is what is meant by working software over comprehensive documentation. Deliver the software, not the documentation.
Having said that, agile teams also produce do less documentation internally. The rest of this article will explore why that is so.
There are two main purposes for documentation in a project:
- Documents are a form of communication between the various parties involved in the project
- Documents are a point of reference on the various aspects of the software system
Traditional processes are reliant on documents because it is the only form of communication. Once the spec is signed off, communication with the customers slows down to a trickle. Secondly, groups are isolated from each other. Developers never get to speak to the customers directly, so documents are the only way for them to learn what the customer is thinking.
Agile processes turn things around. Continuous communication with the customer is a key principle of agile projects. Since there is constant communication, the need for documentation-as-communication reduces. There is still a need for some lightweight documentation, but not anything too detailed.
Secondly, with frequent releases, communication can be around the software. What this means is that instead of looking at the requirements for reference, you simply make a release and get feedback from the customer.
Finally, agile teams are cross-functional. Groups that were previously isolated, such as analysts, testers and developers, sit and work together. Again, this increases the amount of communication between groups, thus reducing the need for documentation.
Not all projects have great levels of communication. These projects require more documentation. Other projects can make do with less documentation because communication is better.
We see that reducing documentation is not the cause, but the effect. Teams that reduce documentation in an effort to be agile are getting the cause and effect mixed up. The key is to adjust the communication level and match the documentation to your needs, not the other way around.
This post is a part of the selected archive.