Agile Manifesto number two
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.
- 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.
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
- Individuals and Interactions over Processes and Tools
- Working Software over Comprehensive Documentation
- Customer Collaboration over Contract Negotiation
- Responding to Change over Following a Plan
Feb 25, 2013 @ 11:40:33
This is a narrow view of documentation aimed to be descriptive of what the software is or does. Actually, if looking at it like that, it is redundant, of course. But documenting is actually capturing knowledge in some way, that can be reused and can be consumed easily. The knowledge you need to capture is that one that will produce value. So, to me it is more important to state that we made a decision, why and the foreseen effects than writing about the algorithm used.
In that sense, point A above should be written as “No descriptive documentation about the code should be needed…”, but for sure notes about decisions and the effect on the business value delivered are needed, and that is information the code nor the unit test could give me.
Feb 25, 2013 @ 13:27:21
Thanks for that William. Point A & B above are my observations about what other people are saying about the second value out in the blogosphere. How do you weight the amount/kind of documentation necessary per project?
Feb 25, 2013 @ 16:25:56
Documentation doesn’t need to be comprehensive, and there is a big difference between documentation and comprehensive documentation.
Working software is fantastic, and a big problem in many systems is that documentation gets in the way of producing workable, useable, code. Documentation is sometimes useless and never looked at. This point of the agile manifesto is to prioritize working software, and to not worry or focus on making documentation too comprehensive.
A lot of software code can be self documenting, but there are almost always complex use cases or business logic that need to have more thorough documentation. In these cases it’s important that just enough documentation is created to ease ongoing maintenance.
The way I distinguish what should be documented and what shouldn’t be is based on maintenance cost. If technology is complex to implement or does something that is unexpected or difficult to understand without thoroughly examining every step (or line of code), then it warrants documentation. Another case for documentation is when something has a direct or indirect effect on another system or another part of the application that isn’t inherently clear to the person looking at the system or code.
Think about what happens if it’s not documented well. Developers will spend too much time trying to figure out what a system does, how it works, and how it affects other systems. The developer may also jump in without understanding everything and cause regression bugs, and create technical debt.
So, when you look at the point of “Working Software over Comprehensive Documentation” in the agile manifesto, consider how your documentation lends itself to ease of ongoing maintenance and how easing ongoing maintenance will reduce technical debt and contribute to working software over time.
If you can’t see value to the ongoing future maintenance, then don’t document.
Mar 02, 2013 @ 06:13:02
FYI – I liked this topic so much, that I wrote my article in response to your questions here
http://dandouglas.wordpress.com/2013/03/01/a-little-documentation-please-defining-just-enough-code-documentation-for-agile-manifesto-no-2/
-Dan
Mar 04, 2013 @ 08:01:24
Thanks Dan! Great article, well stated indeed. I look forward to reading your article addressing system level documentation as well.
Cheers,
-Joe
Mar 07, 2013 @ 14:13:18
Ok, I came back to read the posts. Great article, Dan!
And yes, not only documentation can be categorized by “levels”, or what I call operational (code)., tactical (design) and strategic (architecture) levels, but by the actual type of knowledge that is being capture. As I mentioned, we can “explain” what was done, at different levels as Dan mentions, and that helps us understand better than reading the code (my favorite analogy is that of a street planning guy in a city: walk the streets or fly high in an helicopter, each view helps me in decision making).
But also you have other types of knowledge apart from just a description in natural language of what was done. The decision and the why (of making those decisions) are very important. Knowing that we went this way because of a business/market force will help me later when that decision is stopping me from doing something else: maybe the force is gone, or maybe I have to find another way. Without that information, decision making requires rediscovery and more analysis, which mean losing time.
We need to measure that help in terms of development time, reduction of rework/bugs, enforcement of quality properties (non-functional requirements) and actual business value delivered.