Do Agile Methods Require Documentation?

Posted by Geoffrey Wiseman on Jul 18, 2007

Sections

Process & Practices

Topics

Agile Techniques ,

Agile

Tags

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?

1. Back to top

   Agile Documentation

   by Arnon Rotem-Gal-Oz

   Scott Ambler has a nice article on Agile documentation
   
   Arnon

   Reply

2. Back to top

   It depends....

   by Amr Elssamadisy

   I've been on teams that have had very little documentation outside of a few architecture diagrams and a whole-lotta tests. The question is, for those that have little documentation - has this affected the maintainability of the system over time?

   Reply

3. Back to top

   Re: It depends....

   by Chris Matts

   joe.truemesh.com/blog//000056.html

   Reply

4. Back to top

   Agile Documentation

   by Juan Blanco

   We have been following XP for the past 3 years and we have realized the value of documentation, even if is simplistic.
   
   The reason for this is simple, maintanance, support and people leaving. Nevertheless I still think pair programming is the most productive way to share knowledge!

   Reply

5. Back to top

   Documentantion for internal use

   by Deven Kalra

   One of the objections I hear from managers about to adopt Agile regarding lack of documentation is that the code will become hard to maintain by developers other than the one who wrote the code. Yes, tests can take place of the documentation but in practice the code is not 100% covered by tests and not all marketing people like to read tests to understand what the product does.
   
   
   
   What I have done among other things is
   
   
   
   + Have the developers work on use cases and keep them updated with the functionality they are developing. Ideally, use cases should be written by marketing but does not happen as often as we might like.
   
   
   + Once the feature is developed, have the developer write a short note about feature implementation on the team wiki
   
   
   + Keep a running system architecture document. As iterations happen, developers add and update the document.
   
   
   
   The way I approach agile code documentation is that
   
   
   
   + Don't write massive tomes upfront
   
   + Document what you have done not what you are about to do
   
   + Just provide enough detail that is needed to the intended audience
   

   Reply

• Older >