Agile – How to keep track of a requirements document on an agile team

agilescrumuser-story

I understand that User Stories dominate the agile world, but how are these artifacts stored, so that new developers who join the team can come up to speed with the requirements?

What if the User Story changes later, how is it updated and kept as an artifact? I've seen many teams just open a new ticket/feature request/bug report instead of keeping track of the original story.

Best Answer

First off, almost nothing in @DXM's answer matches my experience with Agile, and especially not with Scrum.

The Agile Manifesto states that while comprehensive documentation is valuable, working software is MORE valuable. So, documentation is certainly not a bad thing, but it should truly be in service to creating working software.

Individuals and interactions over processes and tools

Working software over comprehensive documentation

Customer collaboration over contract negotiation

Responding to change over following a plan

That is, while there is value in the items on the right, we value the items on the left more.

Nailing down every detail before beginning to code has proven wasteful again and again, so documentation is generally dealt with in a JIT (just in time) manner. That is, you document what you are actually going to code.

One of the popular ways of doing Scrum is to use User Stories, which are maintained by the Product Owner and kept in the Product Backlog. The Product Backlog is a fairly high-level list of all the stuff that a solution needs to do, and a User Story is generally a nicely sized way to describe each thing on the list. User Stories aren't mandatory, but they do seem to be a good way to not overdo the details and inspire collaboration instead.

So, anyway, when a story is done--the team has created, tested, and deployed something that meets the acceptance criteria, the story is not CHUCKED, it is simply marked done on the backlog--so the backlog does have some indication of what was done in each sprint--stories and the points associated with them. This is what allows you to calculate velocity, and is valuable documentation in and of itself.

All that said, a User Story may be all the documentation needed to understand a requirement, but more likely, it is something to generate a conversation between the customer and the development team. As such, there are any number of things you can do around that conversation. If it's a face-to-face ad hoc thing, as it often is, the analyst/developers can (and possibly, depending on your organization, should) write down whatever decisions were made and save it somewhere, such as a Wiki or a documentation repository. If it's an email conversation, you can save the emails. If it's a whiteboard session, take a picture of the board with your mobile and save it. The point is, these things are what are helping you get the code done, and might be able to help you later if you need to figure out how or why you did it the way you did.

Another method of capturing requirements is to immediately embed them into test cases (which I believe is what DXM was getting at). This can be really efficient, in that you need to test for each requirement anyway. In this case, you can effectively store your requirements in your testing tool.

If a story is completed (and accepted) and then the user changes his need, well, then you probably need to create a new story. If you use a wiki for your documentation, you can link the new story back to the original, and likewise link that original story forward to the new stuff so that someone looking at it knows that things changed. That's the nice thing about wikis -- it's easy and fairly painless to link stuff. If you are doing the test driven approach, you'd either update the test case to deal with the change, or create new test cases for the new story if the new and old aren't mutually exclusive.

In the end, it depends on what your need is. If the main thing is to get folks up to speed quickly, it's probably a good idea for someone to write an onboarding document to help them out. So have someone do that. As I mentioned, Wiki's are a great tool for keeping this sort of thing, so you might consider Atlassian's solutions which can integrate the Confluence Wiki with Jira and Greenhopper for tracking your stories/tasks/defects and managing your project in general. There's lots of other tools out there to choose from as well.

Related Topic