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?

2 Answers 2


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.

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

  • Thanks for your answer. I understand that the working software is more value over the comprehensive documents. But in my case, the product is staying long enough so the team forgot the reason behind the old changes, and the logic is complex enough to understand without some kind of document.
    – ltvan
    Oct 14, 2016 at 4:26
  • For the option 2, I'm not sure I have enough test suite since we also do exploration test. For the release logs / source control, the history is so long. Do you have any example or links that related to this? The other options are fine and I'm thinking more about them. We use Jira internally. I'm thinking about creating new story with the relationship like "replaced by"/"replaces".
    – ltvan
    Oct 14, 2016 at 4:33
  • Ah, I forgot to mention that we use Acceptance Criteria as the source of the test cases.
    – ltvan
    Oct 14, 2016 at 4:40
  • In a long running project, you will need to have a decent level of documentation. Especially when features are complex and change happens often. In one of my projects, we had a nice release notes, a section in wiki which has all the releases listed in order they happened.A page corresponds to each release, where we add the release candidate details, list of business features, deployment details, and all the useful info regarding that release. In some cases we link to jira tickets if additional data is needed. Oct 14, 2016 at 12:22
  • Unfortunately it is an internal wiki link, not able to share with you. But I think you got the idea? Oct 14, 2016 at 12:24

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.

  • We have strict schedule with less people so I don't think that I have enough test case written down. We do pairing between QC/BA and dev to make sure every body understand the requirement clearly.
    – ltvan
    Oct 14, 2016 at 4:36
  • Ah, I forgot to mention that we use Acceptance Criteria as the source of the test cases.
    – ltvan
    Oct 14, 2016 at 4:40
  • 1
    That's precisely why I recommend putting your documents in a place where they have to stay in sync with your code. Agile teams document. It keeps us nimble. Maybe we just don't create the kinds of documents that traditional PMs expect.
    – RubberDuck
    Oct 14, 2016 at 9:25
  • 1
    @ltvan: If the tests don't pass, then you don't have working software. The only way that the tests can get out of sync with the actual requirements is if the tests don't get re-executed for every (externally delivered) release. But then you also don't have a proof that your software fulfils the requirements. Oct 16, 2016 at 10:14
  • 1
    @ltvan I know we're way off topic, but take a word of advice from a guy who's been in the trenches. Every project can be tested and thinking you'll get something reliable, then go back to add the tests is, honestly, insane. You'll reach a reliable product much faster if the tests are there to begin with. Good luck mate. Something tells me you're going to need it.
    – RubberDuck
    Oct 17, 2016 at 10:31

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.