How to manage spec / user stories in Agile/Scrum

Question

One of the common problems with traditional spec is that it's usually out of date. However, if we use a list of user stories as the spec, the thing is that the requirement may be scattered and cannot follow once it becomes complex.

For example, we delivered a user story and some time later, we decide to change some behaviors which make some acceptance criteria of that user story obsolete.

• If we don't update that user story and just create new one, long time later the new member cannot follow the changes. While doing regression test, our QC may miss those old changes. How can we prevent this?

• If we update the user story, then how to version those changes throughout the time?

Answer 1

First of all, agile values working software over comprehensive documents.

If your application's behavior changes, the most important outcome associated with it is that it should work as expected.

Second comes the documentation.

Here is where you would want to think what is your preference for documentation?

1. Do you prefer to keep your user stories updated and/or grouped together?

If so you could create the new story and relate it to the old story with original descriptions. You could write the story and make the "new" acceptance criteria clearer to avoid any confusion.

2. Or do you prefer to use your regression test suite (if you have one) as the key documentation?

If so, reflect the changes there with clarity.

Or prefer your source control logs/release logs/code comments as the key source?

Then have strict commit regime, release documentations, and so on.

Now for post-live reference:

Most of the development projects I've involved, use Jira actively while development is active. Once the project moves to BAU mode, Jira is not the tool that is used often, it could be wiki write up or support manual. Best to stick with what your company adheres to for post-live references.

Answer 2

The User Stories aren't a spec. They're a place holder for a future conversation. Separate the Tests/Spec from the User Story.

In many teams that TDD, you'll hear

"The spec is the test and the test is the spec."

We keep track of the specification as close to our code as possible. So close, in fact, that it's executable code itself. This way, when a new user story comes up that contradicts the original spec, the spec (tests) have to be updated. The spec never gets out of sync with the code.

I hear you though.

But you can't unit test everything! Some things still have to be manually tested!

And you're right, but that doesn't mean that we can't still keep the tests separate from the story. Any QA worth their salt has a bunch of test scripts that they follow when manually testing a system. If the spec has changed, then the QA needs to update their test procedure anyway. So, just like our automated tests, these test scripts are where we keep the system specification.