Agile and Documentation

Someone asked a question about how an Agile book recommended bare minimum documentation and how the idea of the index cards as means of documentation felt a bit “weird”.

I couldn’t agree more. Index cards as the only or primary way for documentation is a recipe for disaster. The Agile manifesto, as outdated as it is, emphasizes working code over documentation. People have misinterpreted it repeatedly for minimal or no documentation. The latter takes away the power of things written down and agreed upon by everyone.

As a SCRUM Master and Agile coach, I manage multiple teams with 60-70 stories per iteration and 5-7 iterations per release. There is no way in the world that I, or anyone else on my team, will spend time digging a cabinet of index cards to find out about the details of a story that happened 3-4 months ago. It just won’t happen.

Instead, we’ve been gradually transitioning to using a modern WIKI, like Confluence to capture and manage requirements. Among other things, Confluence provides excellent traceability and version control through a very usable diff utility. Requirements and stories captured in Confluence are always current and open to the entire team. This includes people that may not be interested, aware or involved with the creation of index cards, but whose knowledge of the requirements is nevertheless critical for the success of the project. Combined with SCM labels and release notes, any person on the team is always 100% sure what’s in Production, what’s in Testing and what’s currently being developed.