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.

  • 1
    The best documentation is working code Commented Feb 22, 2013 at 5:47
  • @RobertWagner how do you imagine business analyst reading the code?
    – andrew.fox
    Commented Nov 6, 2021 at 9:08

5 Answers 5


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.

  • It would be helpful to put exact quote in your answer.
    – Yusubov
    Commented Nov 30, 2012 at 18:19
  • @ElYusubov Which exact quote? The Agile Manifesto? Commented Nov 30, 2012 at 19:12
  • @Mathew , i have added the quotes that have been referred to.
    – Yusubov
    Commented Dec 1, 2012 at 4:18
  • @MatthewFlynn: most of my info didn't come from personal experience, but rather from reading a whole bunch of books and blogs on agile development, if you want, I can give you the list, so you can read them all and then we can compare notes. My personal experience has been scrum as well. In my previous company, we did 5 releases using scrum and 4 of them didn't go well at all. The danger with a company simply "doing scrum" is that majority of places end up doing "scrum-but" or "cargo cult" agile. Our group certainly did that for quite a while. And yes, we had backlogs...
    – DXM
    Commented Dec 1, 2012 at 5:15
  • 1
    @DXM - I have also had mixed results with Scrum, but it has never been worse than traditional SDLC and a few times worked excellently. Commented Dec 1, 2012 at 5:37

[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

  • least accurate
  • hardest to maintain
  • least useful

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:

  • In a backlog, only N number of stories should have detail filled in. The further out a story is, the less detail you should put in it (i.e. don't waste your time trying to define something that will not happen for half a year).
  • Beyond a certain point, "requirements" items should not even be placed in a backlog if they are out more than 2 release cycles (aka potential shippable increments (PSI) ). Even if you know the requirement is important and must get done at some point, resist temptation of adding it to the backlog. If it is really important, someone will remember it in the next release. If no one remembers it, most likely it's because it wasn't that important after all.

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..."

  • +1 for pointing out the difference between requirements and user stories to the OP.
    – Frank
    Commented Nov 30, 2012 at 6:13
  • I just want to add that my team and previous teams havent been story "chuckers". We keep them for reference. Commented Dec 3, 2012 at 3:20
  • @SimonWhitehead: since you were not the only one that made that comment, I updated my answer. My team never threw away a single story either. So how often have you had to go back 2 years in the past and dig up those old stories for reference? And what kind of info did you get out of them. How was the detail of your stories compared to what Bob Martin (books.google.com/…) describes (especially 3rd paragraph under User Stories section? Just curious, were your stories talking points or did you actually capture ALL requirements?...
    – DXM
    Commented Dec 3, 2012 at 3:59
  • ... my team always kept everything but we didn't even have any detail in our stories, so I still don't understand what value those stories provided, but like many others, my boss was very adamant about not throwing anything out.
    – DXM
    Commented Dec 3, 2012 at 4:00
  • The Acceptance Tests you talk of, these sound to me like documented test cases? Am I correct, or are they actual runnable tests?
    – Didier A.
    Commented May 21, 2016 at 2:48

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:

  • The story may say "As a user, I want to see the VAT printed on my receipt, …". Now, calculation of VAT (value added tax) can be a complicated matter and likely needs more work than this story suggests.
  • There may be an additional story that asks for the VAT calculation to be done (say multiply the total sales amount by the VAT rate), but it is likely not to include all variations of that calculation.
  • At first, the team would focus on providing the basic module, say taking a list of goods and their sales price, and returning the VAT amount. That's something that a team can accomplish within a sprint's amount of time.
  • It is likely there will be many more stories to cover all the possible cases for VAT calculation.
  • To keep the many different VAT calculation rules visible across and beyond single sprints, it makes sense to keep a separate requirements document that lists all the various ways to calculate VAT. This document may evolve over time. In fact, adding a new section to it could be part of a story's task to complete.
  • It sounds like you align with @Matthew Flynn in that the Requirements document is written along development, and serve more as a documentation of the actual working of the code, then a before hand list of requirements.
    – Didier A.
    Commented May 21, 2016 at 2:52
  • "... written along development" - that to me sounds too laisser faire. To clarify, requirements are not a by-product, they are a pre-requisite to efficient implementation. In an agile project, however, requirements are written up only to the very degree necessary to implement the next round of development, and not more. The form to do that is a user story which by definition has limitted scope so the time required to implement fits in a sprint. Contrast this with waterfall projects, where requirements are specified to minute detail before proceeding to the next phase.
    – miraculixx
    Commented May 21, 2016 at 10:14
  • It's unclear, because you say that requirements are not the same as user stories, which I agree with. I think of requirements as the exact details of the business logic, which is more like the how, while the user story is the desired state, which is more like the what. So I'm not sure I understand your comment? It seems in your example, you'd capture the different VAT requirements as they are delivered, one by one, as opposed to all at once.
    – Didier A.
    Commented May 21, 2016 at 15:50
  • IMHO if a requirement, like a user story, doesn't specify a desired state, I'm not sure what good it serves to begin with. Indeed in the VAT example, there would be several user stories successively specified and delivered in subsequent sprints. To be sure, no agile method prevents a team from documenting the whole set of VAT calculation rules in one place, it just promotes the idea that there is no point in spending time upfront to write up fully detailed, all-encompassing requirements for the simple reason that the dev team won't be able to implement all at once anyway.
    – miraculixx
    Commented May 21, 2016 at 17:51
  • I'm still confused, the first point in your answer is that a user story is not the same as a requirement. Do you say that you would have another document written at the beginning of every sprint that capture requirements for the upcoming sprint?
    – Didier A.
    Commented May 21, 2016 at 18:07

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.