News

Last week I gave a talk for business analysts in Sydney on “documentation for agile teams”

My talk did not really contain anything too radical, but it did draw a reasonable crowd, with 80 business analysts making time to come after a full day of work.

So why did 80 people turn up when, being business analysts, they are probably already quite good at documenting the things that agile teams need? It is not as if agile is a new concept.

I guess there is still a lot of confusion about how “agile” and “documentation” work together, perhaps more than I thought there was.

In my talk, I skimmed over the link between user stories and documenting requirements in agile teams, then I moved onto a broader discussion of agile, documentation and knowledge management beyond the perspective of just gathering requirements.

I think some people might have been unsure about how user stories and good documentation compete (or work together) in an agile team. So this article addresses that topic, primarily by providing links to some useful information.

In my next article, I will get to the other core topics that I addressed in my talk. My theory that people misunderstand the concept of knowledge management, the concept of what a BA does and the concept of using an agile approach to their work.

As a result of all this confusion, people seem to be caught between two unsatisfactory outcomes:

• Should the team retain a BA to document things the same way they did in other approaches, even though agile teams don’t seem to refer to the documents the BA writes?

• Should the team ditch the concept of documentation altogether and just hope to remember everything that they talk about?

But it should not be like that. With a little understanding, you can see through the mist and find the real answer – which is neither to employ pointless documentation nor to throw away the idea of documentation altogether.

If you cannot wait for that topic then you can see the one-hour long video of my talk here. 

Otherwise, if you can wait, then let’s get the other topic out of the way first – user stories and good documentation are complementary, not mutually exclusive when understanding requirements.

A fairly short version of this whole article

If you work in an agile team then you should collaborate a lot and preferably do a lot of discovery, analysis, creating valuable things, testing those things and providing value to your stakeholders. You can, if you choose to, use “user stories” to help with all of that.

User stories support great collaboration and discussion. But they are not the only tool you can use. You should feel free to document whatever you think will be valuable to your team and your stakeholders.

Any agile people who tell you otherwise are very naughty and you should tell them to stop annoying you. You should then document whatever you think will be useful, including a firm by polite note to the naughty agile person to tell them how upsetting you find their behaviour.

The longer version of this article

Confusing topic number one: Do you document requirements at all in agile teams?

I hear people worry that if they go agile then they will not be allowed to document things, even when it makes sense.  That is a shame because there are two things that I think are equally frustrating:

• Being pushed into pointlessly creating documents that nobody will read.
• I am still surprised that there are teams who have time in their busy schedules for writing requirements that nobody will read; and
• I am saddened that they choose to use their spare time so badly when they could be adding value to users, or at least watching a nice sunset; and
• Working with people who are so behind the times that they are unaware of some of the tools and technology that have been around for 5,000 years or so.
• Writing things down is right up there with ideas like agriculture, the wheel and a morning cup of coffee when it comes to inventions that can make life better.
• It surprises me that some people are still frightened of writing. I can assure you that other people have been doing it long enough to prove it is safe and even good.

When working in an agile team, a better approach is to document things when it is useful to do so. This is obvious, but perhaps not helpful, because it is often hard to know what to capture and when to capture it in the real world.

So here is a link to some guidance on when and how you might document things when collecting requirements in an agile context: “Agile Requirements Documentation, what’s really done” written by Angela Wick.

The article provides some good common sense advice about what typically happens in practice when people want to capture needs on an agile project (or product development team). It is easy to read and pretty useful.

I tackled a similar issue once in an article where I claimed that you can document some things at the beginning of an agile project. Here is the article if you are interested, but I suggest that Angela Wick’s one is a better starting point: Can we document anything upfront in an agile team?

Confusing topic number two: should you use stories when you want to be agile?

I once wrote an article suggesting that you can use the “use case” approach in an agile team.
Some people were concerned because use cases are quite old and the people who use them often still listen to ABBA music. But I still think you should be able to listen to whatever music you like and that you should use any kind of approaches to building value that your team think is sensible.

Having said that, I like to use stories and I find that they add a lot of value. The main reason people struggle with user stories is not that they cannot write them well, it is that they are not designed for writing – they are designed for collaboration, supported where necessary with documentation.

People feel uneasy that their user stories do not replace good, detailed requirements documentation when they miss the concept that it is the collaboration that is replacing the documentation, not the user story.

Or, people feel like they are duplicating work when they write good, detailed requirements and then copy these into user stories. Again though, they are right to see this as duplication, the point they miss is that both stories and requirements are optional approaches that can support better collaboration, discovery and understanding.

So, how can stories help with collaboration, without needing detailed requirements? A good description of this is found here.

The same author, Kent McDonald, also has a great article on what to do if stories are not sufficient and there is an argument for good, detailed documentation.

The second article has some good links to more views, from other authors.

An overall conclusion

There is confusion about how to use good documentation in an agile team when the team is using stories. But stories are not supposed to replace good documentation.

In many situations, good collaboration can (and should) replace good documentation.

User stories are useful for supporting good collaboration and identifying when this should be supported or even replaced with good documentation.

The article by Angela Wick is a great guide for business analysts who want to better understand the general concept of where documentation fits into the gathering of requirements in an agile setting.

The articles by Kent McDonald are also good for giving some context to the concept of a user story and for exploring when good conversations might be insufficient.

Posted by James King
Copyright © James King