Flickr Badge

Tuesday, December 12, 2006

The role of documentation in agile projects

A commonly misunderstood aspect of agile project management is the role of documentation in agile projects. The agile manifesto says:

Working software over comprehensive documentation

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.

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:
  1. Documents are a form of communication between the various parties involved in the project
  2. Documents are a point of reference on the various aspects of the software system
A detailed spec is supposed to communicate exactly what the software is supposed to do, so that consulting the spec is as good as consulting the customer. A design spec is a form of communication between the designers and developers. A user manual is for communicating between the developers and the users. Documents can also be used for reference. If a new member joins the team, she can just read up the documents to figure out what is happening. The maintenance team can read the design doc to figure out the code.

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.


sateesh said...

Nice one Siddhi. I am impressed seeing your profile and read this article. Nicely articulated equilibrium between documentation and communication.

But I am afraid if agile model is going to work in future as I noticed in western countries IT companies are encouraging employees to consider hot desk and work from home policies where we may lag effective communication.

Siddhi said...

Yeah that is true. Agile works best with everyone sitting together. In an offshore scenario or work at home, you need to adjust accordingly.

First, how can the amount of communication be increased? Some companies are using Skype/IM between groups.

Second, the amount of documentation needs to be increased to compensate for reduced quality of communication. The team needs to make a call on how much is enough.

Anonymous said...

Nice article Siddhi.. As you pointed out, liteweight documentation for Agile... does it mean that feedbacks/MOMs should be consolidated and used for final documents.

Further, what is the role of design in such cases ? Is Architecture and specs are not well defined if so how you can develop a workable software ?

Can you throw some light on the change requests and change control mechanism to be followed while updating the codebase in Agile.