“Working software over comprehensive documentation”
Of the four agile values, this is probably the least understood and most often misinterpreted. It certainly does not say that there should be no documentation as some (the less ambitious developers and teams) propose. It says that there is more value to actual software than comprehensive documentation.
While I have a great deal of affection for the Agile Manifesto (I believe that dedicating an entire series of blogs to just this particular topic demonstrates this abundantly), I think that the original writers could have been more specific to remove some of the confusion and misinformation that has sprung up around this value. It might have been more appropriate if the original writers would have said, ”Working software over comprehensive requirements and design documentation,” because I think this is more what they meant.
This level of specificity would keep teams from using the excuse that there should be no documentation at all. We have to remember that the writers of the manifesto were doing so as a reaction to what they perceived to be short comings in the prevalent way software was delivered. In that phase—gated approach, copious documentation of requirements and design were produced before any substantive software was developed. Prior to the manifesto, comprehensive documentation could be delivered but working software was either not delivered or poorly delivered because so much emphasis was placed on requirements and design documentation.
In other words, documentation is important but it should be less important than actually building the software. What is the use of great documentation of a system that is poorly or not fully built? Also, documentation tends to be easily outdated so I suspect that the writers of the manifesto were also alluding to this fact. Why create copious amounts of documentation that does not match the final product? Or why spend all our time updating copious documentation as the product changes?
There are usually two types of documentation — internally facing documentation, like design and requirements documents, and externally facing, like user manuals. So far my argument has been for these internally facing documents. Agile addresses these with user stories and acceptance criteria. I like to attack internal documentation using Behavior Driven Development (BDD) since then the code always matches the internal system documentation (see Specification by Example).
What about external documentation? It might be that they would argue that good design would preclude the need for end-user documentation. I suspect the writers of the manifesto would agree since they are user-focused and that they would be more supportive of more of this type of documentation versus internal documentation.
Also be sure to check out the other post in this series:
Agile Values: The Importance of Individuality
Podcast: Play in new window | Download
Subscribe: Apple Podcasts | Android | RSS
One Reply to “Agile Values: Working Software Over Documentation”