Do Agile Methods Require Documentation?
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?
Re: It depends....
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!
Documentantion for internal use
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
Uwe Zdun, Rafael Capilla, Huy Tran, Olaf Zimmermann Mar 09, 2014
Olav Maassen, Liz Keogh & Chris Matts Mar 08, 2014