User stories as way to document point-in-time specification of product

Question

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.

Answer 1

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.

Answer 2

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.