We have an existing software product that is being transitioned over to a agile process.

New requirements will be captured as user stories, but this has inspired the question around what to do with existing requirements and what the relationship is between user stories and product specification/documentation.

I can see value in capturing all the currently implemented and new requirements as users stories as a way to answer the question: "What exactly can users do with the product at this point in time?".

I don't specifically have a need for this right now but I can see it being useful to be able to show a customer: "Here: this is exactly what the product does". This may as be a good way to track our contractual commitments, or even a buy-out checklist.

In general though, user stories are used as a tool to capture and implement new requirements - and as far as I'm aware people rarely delete a user story once the requirement becomes obsoleted or not needed anymore. And without doing this 'pruning' you no longer have a full specification of your product functionality at a point-in-time.

I suppose the other way to capture this specification is via acceptance tests (Executable Specification thesis). With something like gherkin you have a tight coupling between story, acceptance test and specification.

TL;DR: If I wanted a way to capture a point-in-time list of functionality or "specification" of my software product, how would you go about it? User stories via an appropriate tracking tool seem to give us the power to do this but I have never seen them used for this.

Note: The team is already fairly familiar with agile so this question not about them getting familiar with the process.

  • Do you have good end-user documentation for your software? If so, you already have a fairly good equivalent to a specification. This is probably good enough -- I would not bother with user stories for existing software. Feb 22, 2017 at 8:07
  • No we don't have good documentation. I suppose this question is exploring the idea of whether user stories can be used not just for collecting and implementing requirements, but also to serve as a catalogue of current functionality - perhaps even then being able to generate documentation mechanically by combining stories, tests and code comments etc.
    – Schneider
    Feb 22, 2017 at 23:06
  • "you no longer have a full specification of your product functionality at a point-in-time." -- Yes you do. Your software (and its test suite) is the specification. It always was, but your documents lulled you into believing otherwise.
    – RubberDuck
    Feb 23, 2017 at 10:40
  • If you don't have good end user documentation, that may be more valuable than user stories only read by engineers. Software is not a specification; I am not sure why anyone would suggest that. By definition, the software is the implementation of the specification (missing in this case). Feb 23, 2017 at 16:01
  • @RubberDuck I agree philosophically that the software is the spec (or at least the embodiment). But I am looking at this from a more practical perspective. If i want to know if my software will satisfy a new customer I don't want to have to explore the running software. It would be nice to point to an entry in a system (whether that be a story, a test etc) that can say "yup it does that"
    – Schneider
    Feb 23, 2017 at 23:36

2 Answers 2


Personally, I would not allocate any resources to reverse-engineering user stories on an existing application all at one time.

Start with the new requests to develop good practices with this process (getting feedback from clients, generating users stories, using them for development and finally having features tested and approved.). Everyone should become fluent and efficient.

Once everyone involved is proficient at the user-story process, gather additional stories on features or sections of the app related to the new features. The goal here is to identify what users really want (maybe a feature can be removed?), so no one accidentally takes away something necessary. I think this is a more efficient method because the developer is familiarizing himself with a certain part of the code base already. Use that knowledge to develop more specification.

Remember, users stories are what the user wants from their perspective. There isn't anything on how this gets accomplished. A testing suite could help accomplish this or additional requirements documentation, but you need to have a team with some fluency in this area. Teams that struggle with writing tests, just like writing user stories are not going to be able to create something very useful. They're struggling to just make it work.

The key is to make sure your adoption of these new processes (user stories and tests) is successful. It takes time. If you're still practicing these things, it's not likely you're going to get as much out of them as you may think. Everyone will be frustrated with the process and this will end up being a waste.

  • Thanks for your answer. I've added a note to my question emphasising the team is already fairly experienced with agile. It's more about the transition, and further: whether user stories can/and should be maintained as a point-in-time catalogue of product functionality.
    – Schneider
    Feb 22, 2017 at 23:02

User stories can also help set expectations on what we expect the users to and how they are expected to deal with system limitations / error states.[1]

If you have system specifications (I'm thinking of them more as pre-agreed upon limitations) that cannot be describe in user stories directly, try describing what will happen when user is at the system limit and what happens when they go beyond it.

[1] : This is just documentation. Do not force users to follow the user stories. If there's a gap between what users are doing and what you expect them to do, then the requirements were not good enough the first time and need to be revisited.

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.