Agile Manifesto number two

By Joe in Agile Other on February 25, 2013

Image 0888 full 2x

Working Software over Comprehensive Documentation

One of the things I enjoy about the Agile Manifesto is it’s depth whilst remaining simple. For instance, the left part of the statements (in this case “Working software”) are preferred to the right (“comprehensive documentation”) though the right is recognized as having importance as well. It’s through comparing the value of one part to another that it eloquently lays out the algorithm for how to evaluate choices in an Agile manner.

In my journey to becoming an Agile Coach I’ve read many articles written by people using Agile to work on interesting projects. Often I run into an argument about the need for documentation and, as I see it, it tends to run along these lines:

A) No documentation is needed with well built software and unit tests, because the software should be intuitive and the unit tests read as explanations of the software they test.

B) Documentation is needed on complex systems for other developers to understand software they will have to support but did not create.

I think it is important to note what sort of documentation they are talking about.

At the end of the day, it’s up to the customer to decide what is more valuable to them. Writing documentation is not just heavy in time to create it, it is also extremely difficult to maintain. But that doesn’t mean that it should never happen. There may be circumstances when small amounts of comprehensive documentation would be needed. For instance, if an API has a wide range of uses and it is important to point out the features that may not be immediately intuitive. Plus the people using the API would not usually have access to the unit tests that describe it.

Either argument may be Agile as long as they weighed the solution on it’s independant circumstance and not as a rule of thumb.

Are you an Agile Coach or do you work as a developer on an Agile team? How do you view the need for documentation on your projects?

Agile Manifesto

  1. Individuals and Interactions over Processes and Tools
  2. Working Software over Comprehensive Documentation
  3. Customer Collaboration over Contract Negotiation
  4. Responding to Change over Following a Plan

Learn more

Collaborating with the future: How to leave a lasting impression