Monday, December 08, 2008

Agile means no documentation - common misconeption

Before I begin my Agile training programs, I provide an opportunity for the participants to share their understanding about Agile. Most commonly heard definition include
"Agile = No Documentation".

This is the most commonly misused and mis-communicated definition. I don't blame the newbies however it is the value

Working software over comprehensive documentation

that has been defined at a higher level of abstraction by Agile Manifesto that creates such a misunderstanding coupled with inexperienced Agile evangelists.

For most of us, as soon as we hear the word "documentation", the first thing that comes to our mind is the "Microsoft Word" document, and the ISO-CMM level prescribed requirement/design documents that we might have written in the past, isn't it ?
So, when a newbie reads the documentation related value from Agile manifesto, they generally assume that one needs to dump documents, and rely purely on running code(working software). However, Agile manifesto is trying to say that "prefer" working software over (not abandon) comprehensive documentation. What it means is, try to create working software, because this is the only thing that adds value to the customer's business and not the extensive documentation.
Next question I generally get is "if we don't do extensive documentation, then how do we retain the knowledge ?', "what is the contingency plan for attrition as this would result in loss of precious knowledge ?"
My take on this is, "do document" in whatever way you can to protect the customer/yourself/project to retain knowledge. Agile value is trying to say that, don't do documentation for the sake of doing it, however document information from the context of adding value to the customer.

In one of my past experiences working on an Airline and defense related projects, we had applied Agile methodology, and found that extensive documentation was indeed a must to conform to various standards. We wrote necessary documents as it added value to the customer, and customer was willing to pay for that.

Documentation not necessarily mean capturing information on "Microsoft word" ! one could write something on the white board or flip chart and take pictures using a digital camera. The images stored could be considered as a project document. Similarly, recorded videos, good java docs(for example), screen captured images, etc could well be considered as project documents.


tbiz said...

Would appreciate your views on the book about agile documentation patterns.

Kimota94 aka Matt aka AgileMan said...

Good points, all.

One thing that going Agile really affects, vis-a-vis documentation, is the rate of change. In the company where I was the Agile Manager, we adopted an Agile methodology because we couldn't keep up with the rate of change our owners/customers were experiencing if we did things the traditional way. However, once we started doing 1-month Iterations, the rate of change increased even more, as those making the requests now assumed we cold adapt to anything!

In that scenario, doing comprehensive documentation is a huge challenge, because you're constantly trying to hit a moving target. So one bit of advice that I'd offer from that experience is that you should work out with your customer, in clear and precise terms, what degree of documentation they require (you can worry about what documentation you need internally yourself). Once you have that decided and agreed upon, then you can account for the time to produce documentation in your estimates or velocity when you plan. Without that in place, you may run into all kinds of problems later on when your customers express shock and outrage at how little documentation is available reflecting their constant changes in direction.

Anonymous said...

It was rather interesting for me to read this article. Thank author for it. I like such themes and everything that is connected to them. I would like to read a bit more soon.

benspikey1 said...

Nice, simple truths.. enough said..

Anonymous said...

I work in company on application that is used by around 2mln people, but they all tell me that agile means no documentation at all, comments in code only in header of file (only meaningless info about when file was created etc, nothing more) so working on a few million lines of code without documentation and almost no comments in code is lets say "interesting" experience :| but I'm only young and stupid junior software engineer. People are leaving and then no one knows how some parts of the app work and they still have problems with regressions because no one even knows how app should behave haha.

Venkatesh Krishnamurthy said...

It is just unfortunate that, Agile values/principles are being mis-interpreted. If documents add value to business and the project teams, just do it. At the end of the day, the metholodologies are designed to help the business and team, and not to block them.