Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
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.
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.
[update #1] As @MatthewFlynn pointed out, his experience with agile as well as many others (including my own) is very different from the answer that I'm providing here. The answer here is based on my observations of what did and didn't work on my own team in the past, combined with many books and blogs that I read on the subject...
most of the drive towards agile development is specifically targeted at eliminating requirements documents.
Agile tries to do away with most documentation and I agree with their ideas but of all documents, requirements have by far the largest bull's eye painted on them. The reason for that (IMO) is that requirements docs are furthest away from actual working code and of all the documents, that makes them
To guide the team as to what should be developed next, Agile replaces requirements documents with a backlog of stories that identify what you should working on next and highest priority items with largest bang for the buck (both present and future buck) are typically placed first in that list.
However, a backlog should not be confused with a requirements doc:
Once a story is completed, that story gets removed from the backlog and is CHUCKED(1). Again, stories are not requirements. They ONLY tell the team what to work on next; they are not for historical record.
However, in proper agile process, whenever you deliver work, part of that delivery should be unit/integration/acceptance tests. These tests are very valuable because they have many purposes. I won't get into the full list, but one of those purposes is documentation for your current production software.
A test documents how the software should behave given a certain set of inputs and preconditions. It also documents how to use public (and internal) APIs of your code. It also serves as a safety net so that when a new developer enters a team and inadvertently breaks something, that error will be caught as soon as it is checked in.
Agile process obviously promotes taking advantage of automated unit tests as much as possible but we all know that not every single thing can be automated. Your software suite will always have a set of tests that have to be executed manually. However, a) your developers should be actively working on automating as much as feasible and b) manual set of tests should be regularly executed by your QA team so that any break in functionality is discovered as soon as possible.
(1) - Since I got several responses for the "chucked" part. In 5 years since moving to agile, my team never threw away a single story, even 30% of those that got scheduled, then deferred and then forgotten. My boss wanted to keep them "for reference" and yet no one has ever looked at any of those stories.
People are generally attached to their data and I know it's hard to fathom throwing something out once you already have it, but keeping inventory (whether physical or electornic) on hand isn't free and the more I think about it, the more I agree with the "chucking". This is from "Agile Software Requirements: Lean Requirements Practices for Teams, Programs, and the Enterprise" (p.190) - "User stories can be safely thrown away after implementation. That keeps them light-weight, keeps them team friendly, and fosters negotiation, but acceptance tests persist for the life of the application..."
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.
Managing any documentation can be difficult regardless of whether you are using agile stories or a big up front document, and in order to reduce the burden, the documentation should be minimal and updated incrementally to match the efforts being made on the tests and implementation. As the OP has alluded to however, simply updating the documentation risks losing the history of how the software has evolved over time.
Is this really important? Sometimes it can be. For the most part you simply wish to view the stories/UML/whatever along with the tests and the code itself at the present time, however when questions are raised as to why a feature has been implemented in a particular way, it can often be useful to look at the history in order to see how the feature has changed over time, to paint a clearer picture as to why implementation option X was chosen instead of option Y.
There are a couple of ways that you can keep track of such artifacts. One of the better options can be to keep your stories in a tool that allows you to have your story text versioned in a similar way to the versioning of your source code. Wiki's tend to be very good at this, and so too are some of the project/issue management tools, such as Trac or Redmine which keep histories of changes to the issues themselves, as well as the wiki pages within these systems. This can be taken a little further though, to improve the ability to trace changes from issue to feature, by ensuring that new stories or issues are linked in some way to older related issues and stories. This could be as simple as adding an older issue/story id to the text of a newer issue/story, but can be improved greatly by including any issue or story id's to the check in comment whenever you commit a change to your version control system. This method is of the greatest value however if your commits are frequent and limited to a single story or issue.
The biggest difficulty of course is that this type of approach requires careful attention and a commitment by every team member to be consistent, and to keep their commits small and frequent, and for those managing the stories and/or issue/project tracking systems to keep on top of the artifacts which provide links between the present state of your implementation, and all of the changes which have previously occurred.
It has been said before but I think the gist of it is this:
requirements may cover many facets and typically result in more than one story.
a story organizes a team's work in chunks that are small enough to fit within the time boundaries of a sprint.
often there are many details that need to be defined for some particular function to work correctly. This is when it starts to become useful to keep these definitions in a seperate requirements document - for clarity, common understanding and later reference.
Consider the legendary online pet shop example:
You can use freemind to gather the list of features. How it is done, take a look into this tutorial (somewhere in the middle).
When you have list of features, you go with writing user stories. This can be done by using a simple text file, or word document, or something as complex as a agile management tool.
When you finish with user stories, they are prioritized. Later, from the user stories, people produce tasks, people take tasks and implement it in code.
All this can be seen how a c# project is managed from the start in the autumn of agile video cast series.
