Tuesday 15 April 2008

Agile Documentation

So, we've spent the last three years introducing agile practices to those lucky enough to be involved in creating software in our department. All of the developers have been on the "How to be an Agile Developer" course run by exoftware. We've had numerous consultants and coaches coming in to help us out, including Rachel Davies from Agile XP and Antony Marcano of testing reflections fame. Also, everyone has been to the certified scrum masters training. All of these approaches to getting our department up to scratch have been valuable and I highly recommend them. OK, except for the scrum master certification which was useful but should be called an introduction to scrum.

Training is a good start but nothing can replace actual experience on Agile projects. After working on and with Agile project for three years I feel I'm "proficient" in using Agile practices and coaching teams in their use. By proficient I'm referring to the dreyfus model of skills acquisition. I generally work on intuition but sometimes refer back to the rules especially when I need to backup my arguments. Referring to rules is helpful to anyone learning Agile or in fact learning anything, because we all start out needing a framework for making decisions when learning something new. Our introduction of Agile working practices has really taken hold and has now been adopted as a standard working practice department wide. Job done I thought and have been busying myself on many of other things that require my attention whilst leaving the project managers and tech leads to get on with running their projects.

You can imagine my surprise when I received an email from one of our project managers this morning with a list of story cards for a project we're starting. Great I thought, let's get started. It wasn't the story cards that surprised me. It was the last line of the email that read

"I’ll need to write a spec to flesh some of them [the story cards] out".

As I stood up to walk over to her desk and ask why she thought she needed a spec before a release planning session I saw a 27-page Functional Specification on the desk of the guy sitting next to me for part of a different project which is also just starting.


How had I been walking past this pile of papers for three days and not noticed what it was? How does a functional specification fit within an Agile project? Why are we taking a step backwards? Are we becoming WAgile as Jason Gorman would put it? Were we ever truly Agile? What does truly Agile mean anyway?

On further investigation I'm told that these "specs" are not meant for the developers and are used to help the project managers track changes. Looking at one closely reveals it includes thorough details on every action a user can take and the expected result for the entire application. So let's think about that for a second. An Agile project which is changing every hour or day and the project managers are wasting their time updating a functional specification to reflect the changes.... and it's not for developers. Who is reading it then? All this time wasted while risks and issues around the project are possibly not being dealt with.

Now don't get me wrong, I think documentation is extremely important and most of the Agile teams I've seen don't create enough documentation. However, if you need a brief document explaining what a system does and how you would use it, start creating it towards the end of a project when you know more about what it's really going to do. Don't create it before the project has even started and a single line of code has been written.

Finally, for those of us who are still learning to apply Agile practices in the real world I refer back to one of the principles of Agile development according to the Agile Manifesto.

"Working software over comprehensive documentation"

That does not mean no documentation. It simply means we prefer working software over comprehensive documentation. I would encourage all of you to stop writing documents that have no value and instead, talk to the people in your team. I would also encourage you to only write the docs that you can prove add value to your team.

My approach to this situation would be to call a release planning session so that we can talk about the cards in question and change them to be more clear where they need to be. I'll also be recommending that the time is spent working on acceptance criteria or tests associated with the cards rather than trying to write a functional specification about them. Story cards and their associated acceptance criteria seem to me to be the most valuable pieces of documentation needed at the beginning of a project.