Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Do Agile Methods Require Documentation?

Do Agile Methods Require Documentation?

Some believe that Agile doesn't require (or, even, cannot support) documentation.  An Agile case study in CIO magazine called it out as a misapprehension.  Frans Bourma recently wrote about agile methods and documentation and Ian Cooper picked up the thread from there:  "It may be time to put the record straight."

Ian starts with the agile manifesto, which talks about valuing working software over comprehensive documentation; he argues that the manifesto is a set of base principles, criteria for determining if a process is agile, rather than a specific methodology.  He puts this principle into a context to help describe what the principle is fighting against:

To understand the the admonition it must be remembered that the non-agile methodologies were often characterized as document-driven development because they required the production of innumerable documents before a line of code could be written. In many cases the process steps were being performed by software development teams simply because the methodology told them that they had to be performed, even when they provided little value. As a reaction many development teams abandoned methodologies altogether. Agile was an attempt to remove the production of documentation without purpose, and focus once again on the key artifact of the software process: the code. Unfortunately many people who have never practiced a full on waterfall process like SSADM, do not recognize what is being rejected, and thus assume the limited documentation of ad-hoc or in-house processes was being targeted too.

Reviewing how Crystal handles documentation:
Crystal considers development to be a series of co-operative games, and the provision of documentation is intended to be enough to help the next win at the next game. The work products for Crystal include use cases, risk list, iteration plan, core domain models, and design notes to inform on choices. Crystal also defines the roles for these. Note however that there are no templates for these documents and descriptions are necessarily vague, but the objective is clear, just enough documentation for the next game. I always tend to characterize this to my team as: what would you want to know if you joined the team tomorrow.
And Extreme Programming:
XP by contrast notes that documentation is not needed so much inside the team, as outside, and sees it as a costed story that needs to be delivered. The goal here is, I suspect, to reduce unnecessary documentation by forcing it to be evaluated alongside other feature sets. XP relies more heavily on programmer-to-programmer communication to distribute knowledge about the system than written documents, but mandates pair-programming to make this possible: because you share understanding with others through pairing, there are no 'dark areas', and less need for people to document what has happened. In addition the code and tests are seen as then primary repository of detail on how the software was implemented, for fear that documents always grow out-of-date ... the summary is whatever the team needs or the customer wants.
How much documentation do you use in your agile projects? What has worked well for you, and what hasn't?

Rate this Article