AgileTHIS

We all have an ideal view of the world surrounding us. That is OK as long as we are aware of the real world and know how to rationally deal with it. We as agile practitioners have our own view of an ideal world. Last year I attended Scott Ambler's session on "Agile in Practice" at Agile 2008. In this talk, he challenged the common concepts and shared his findings. I found this talk very insightful and would encourage everyone to listen to this. In fact, it inspired me to write this series on Agile ideal views of the world.

I will talk about some of the "aspects" of this ideal agile world in a series of blogs. Last time I talked about "project management (PM) tool vs. no tool." The topic today is "documentation on Agile projects." This is third in the series.

The common perception about Agile projects in the market is that Agile teams follow cowboy coding and hence do not document. The myth about "no documentation" goes so far as that some see this as an incentive to adopt Agile and escape "over documentation" of the traditional waterfall projects. However, this couldn't be further from the truth. This misconception to some extent stems from misinterpretation of the Agile manifesto that says-

"Working software over comprehensive documentation"

The intent of this manifesto is to underscore the importance of "working software" and risk of "comprehensive documentation." This does not encourage us to do away with documentation altogether. I hope we all agree that the primary goal of any software project is the "working software," and the secondary goal is to support on-going maintenance and enhancement of this software. Scott Ambler refers to it as "to enable the next effort." We all know that cost of development is only 20% of the total cost of ownership of a software. To contain this cost and associated risks, we need "right documentation."

A few of the issues with the traditional documents are,

1. Documents are static. They are a snapshot in time. Hence, they quickly get out of sync with actual working software. Outdated documents increases project costs and risks.

2. Documents are created too early. Traditionally documents like requirements, architecture, design documents are created early in the project. As the project progresses, the requirements, architecture, and deign morphs. Either documents become stale or the cost of maintaining documents increases.

3. Documents are bulky. We tend to use Word doc, Excel, Power Point and the like to create our documents. They are disconnected island of information. To keep them in-sync with each other requires a lot of effort. As a result, we see a lot of repetition (wastage). It is also difficult to link information across all documents at the appropriate level using these old-school tools. For example, individual requirements to rules to test cases to decisions to etc. etc. It is difficult to browse the right related information just-in-time and just-in-place.

DDJ (Dr. Dobb's Journal) partnering with Scott Ambler ran a survey on how much documentation Agile and non-agile teams are doing. The result reveals that Agile teams are more likely to model than a non-Agile team and equally likely to create documentation.

Here are a few things I suggest to become Agile with documentation.

1. Certainly, no documentation is not Agile.
2. Find a way to implement a continuous, collaborative documentation (Wikipedia model). For example, allow end users to evolve and enrich user manuals as needed, when needed. Allow developers or support engineers to update architecture document or operational manual.
3. Delay documentation until it is requested. I call it "just-in-time documentation."
4. Keep the documents nearest the location of use (context sensitive). I call it "just-in-place documentation." For example, technical API documentation within the source code. Use tools like NDoc/Java Doc/RDoc to extract APIs accessible from IDE. User manual should be embedded through out the software.
5. Use Wiki or Wiki style tool to cross link different elements of documents to form a Web of interrelated information. I call it "accessibility of documentation."
6. Determine what to document based on frequency of use and number of consumers of the information. Importance of a document can be calculated by multiplying frequency and number of users. This could be used as a surrogate for a real ROI. The higher this number, the higher the ROI from the document. In other words, only document information that will be used by at least a group of people on a regular basis.
7. Use appropriate format for documenting information at hand. I call it "comprehensibility of documentation." For example, use "As a , I want ...., so that...." for documenting requirements. Use "given ..., when ..., then ..." (BDD style) to document acceptance tests. Use state machine diagram to document a stateful processing of data.

Scott Ambler goes in depth about documentation on Agile projects. I would encourage everyone to read the article.

Yes, documentation is a sticky topic. It is difficult if not impossible to strike a balance between amount (over vs. under vs. no) and quality (useful vs. redundant, correct vs. stale) of documentation.

What type of documents are you creating on your Agile projects? What tools are you using?