3

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

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 '16 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 '16 at 4:33
  • Ah, I forgot to mention that we use Acceptance Criteria as the source of the test cases. – ltvan Oct 14 '16 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. – Mincy George Oct 14 '16 at 12:22
  • Unfortunately it is an internal wiki link, not able to share with you. But I think you got the idea? – Mincy George Oct 14 '16 at 12:24
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.

  • 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 '16 at 4:36
  • Ah, I forgot to mention that we use Acceptance Criteria as the source of the test cases. – ltvan Oct 14 '16 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 '16 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. – Bart van Ingen Schenau Oct 16 '16 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 '16 at 10:31

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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