Get certified - Transform your world of work today

Is Documentation Really Wasted Effort?

01/26/2012 by Vadivelan Sivanantham

A widespread myth I've noticed in Agile software development is, "No documentation in Agile" or "Documentation is wasted effort." Particularly during a transition from Waterfall to Agile, we appreciate the benefits of adopting typical Scrum practices, such as short iterations, timeboxing, daily scrums, retrospective, and so on. We also try to get away from the tasks and activities that we found monotonous before Agile adoption — documentation, writing proper code comments, etc. But is it really correct to completely stop documentation and code comments?

Let me share one of my experiences related to this question.

I was the Scrum Master for a team that had just moved to Agile methodology. We were about to make our first release (after three sprints) to production, and we decided to set up a separate meeting to hand over the code base to support team to help them understand the changes (development and support teams were separate entities in that organization). There was a great deal of debate about documentation during that meeting. The support team was expecting some sort of documentation (at least high level) on the architecture and a few comments in the code to help them understand the logic.

The issue was addressed by putting in place the following practices:

  • The Scrum team would hold a detailed knowledge-sharing session with the support team, to go over the new features, any architectural changes, and complex logics in the code.
  • One developer from the Scrum team and one support person would swap roles. This would help the support team operate more independently, with a Scrum team member on board.

Looks logical, doesn't it? The practice worked for more than 15 iterations without any issues. Many features were incrementally added to the product, and there were some code refactoring as well.

However, there was a special business requirement: We needed a specific product for a specific set of customers, a product that customized some specific functionalities and features. After a lot of analysis, the team decided to set up a separate component (a replica of an existing, developed component) with add-on features specific to those customers; it could be plugged into the existing system as needed. Thus we created loosely coupled components and avoided increasing the code complexity of the existing component. A single developer was involved with both the original component and its customized version. Makes sense, doesn't it?

In fact, that component used numerous complex code logics. The developer spent more than a week understanding the code logic he'd written a year before. He did manage to figure out the logic and completed the required changes in the component. And the product was in fact deployed to production after testing — and after resolving a series of post-production defects that the testing identified.

We held a dedicated retrospective on this component and its production. Our key observations and outcomes were as follows:

  1. The developer who developed the component felt guilty that it took him nearly a week to understand the logic he himself had written a year previously. That leads to a lowering of motivation.
  2. To cover that up, the developer put in a great deal of effort (in other words, stressed himself) in order to complete the component customization. This made him to miss a minor logic issue in the code, which led to a number of defects. In other words, the result was less productivity and lower quality.
  3. Our cost-benefit analysis looked at "not including code comments during development" against "time spent in understanding the code logic after a year." We noted that it would have taken the developer ten minutes to write the code comments at the time of development, and that step would have helped him to later understand the logic much more quickly (in perhaps 30 minutes versus one week).
  4. As a result, the team agreed to include minimal documentation and minimal code comments as required in order to avoid this sort of issue in the future.

We learned the hard way that in Agile development, we should have minimal documentation rather than no documentation. The decision about what level of documentation for which components and code logics remains up to the team to decide on a case-by-case basis.

I hope our experience will help others learn the importance of the step more quickly than we did. I would be interested in your own thoughts and experiences related to documentation and Agile.