The role of documentation in agile projects

Posted on December 12th, 2006 in Agile, Methodology by siddharta || 3 Comments

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.

Doing Distributed Agile?

Share and collaborate with distributed teams with our electronic agile board tools. Get all the benefits of electronic tools without sacrificing the benefits of physical boards. Supports Scrum taskboards, Kanban boards and user story maps. Check it out!

3 Responses to “The role of documentation in agile projects”

  1. Balwinderbajwa Says:

    David,Hope you are well. I agree that for Agile to be successful, it reierqus that the Developers are put directly in touch with the Users. I am not certain that Technical Authors are always the best go-betweens or even coordinators it depends of course of their abilities. A Technical Author will benefit from understand the users perspective and ensure that the perspective is reflected in materials prepared. For the software to meet requirements, a person is required that drills down into the true needs so that the software is developed to actually meet the true needs rather than developed to meet the perception of the needs. Agile introduces a considerable risk that the software that is developed is designed’ by the users. Users are not designers of software they are able to describe the problems they have, but not necessarily design the solution that best addresses these problems.

  2. Felisa Ryhal Says:

    I like this site because so much useful stuff on here : D.

  3. Erik Hickock Says:

    Pax Christi!

Leave a Reply