Agile Manifesto number two

By Nathan Donaldson

Tags: Agile , Other

Here’s the second in a series of posts on the four values of the Agile Manifesto.

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.

Types of documentation

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

• Is it a large document defining all the features and interactions of the product before it is made? I would argue that approach is not Agile. It breaks three and perhaps four of the Agile Manifestos (2,3,4 – see below) so I don’t imagine that is the issue.
• Is it the Help documentation a user references (search/tutorial) to learn how to use special features of the software? No, that sort of documentation is more of a feature to be requested from the client.
• Is it a large document describing the API and explaining the theory behind the features for future developers? I think this is the brunt of it. This could be an actual written document or a reference to detailed comment blocks around each bit of code. While this is not preferred and may not be as lean as it could be, it technically does not violate the Manifesto. After all, the line uses the word “OVER” it doesn’t say Working Software NOT Comprehensive Documentation. The only thing the Manifesto is asking is that if you decide to create comprehensive documentation, you first ask yourself if there is a better way to accomplish the same thing.

Weighing up the benefits

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: Documentation and how to leave a lasting impression

How to deliver working software every Sprint