Agile Requirements - what's beyond the user story?

In the my Previous blog I talked about a metaphor to illustrate requirements evolving from a 1-liner, to a paragraph, to a 1-pager, and then to multiple pages. In the process of building systems using agile approaches many teams have forgotten, or worse have never known how to document details around requirements. There's that pesky agile value - "working software over comprehensive documentation." Too many teams take this to mean we no longer have to write anything down. Not so fast cowboys.


We know about the 1-liner: "As a ...  I want to ... so that ..." If written well this alone gives us good information.  In most circumstances this isn't enough, so we add acceptance criteria. Now we have a paragraph - the 1-liner plus acceptance criteria. What's next? One choice - nothing else is needed. This may be enough. But I think there's more that can be done.

When I teach requirements classes, I'll ask the students to guess what requirements related artifact, beyond a user story with acceptance criteria, I would choose if I could have only have one type of requirements related information documented. What do you think I would pick? What would you pick?

I would be pick test scenarios. If you have a user story, the acceptance criteria and test scenarios you're golden in many circumstances. Continuing to use the metaphor, this approach includes the user story, the acceptance criteria and the test scenarios (or cases) - you now have a 1-pager (or more).

Test scenarios can take several forms including the Given, When, Then format from BDD. You can also go down the FIT/FitNesse route.

Much like developers building systems using TDD, teams can use Acceptance Test Driven Development (ATDD). I've also heard and used the phrase executable requirements. No matter what the name, the idea is that there are a set of scenarios created to verify the system under development.  Here's a example using BDD:

• Scenario: A library patron with unpaid fees can't check out a book
• Given a patron checked out one or more books
• and the patron failed to return them on time
• When the patron attempts to checkout another book
• Then the patron won't be allowed to check out any resources 

If you were to use FIT/Fitnesse you would build test tables. For a similar case you might have the following table:

Account #	Outstanding fees on account	Patron Result
123-456	$0.00	Checkout book
987-321	$10.00	Not allowed to checkout book

This is, of course, a very simple example. Look at the FIT/FitNesse website for additional scenarios. This type of test development sets up the team for automation. A goal all teams should have.

This is fancy and all, but does anyone actually do this? The answer is, "yes." In one example where I was leading several teams in creating a loan processing system, we delivered user stories, with tests and test data as a requirements package. As you can imagine a loan processing system has many, many scenarios and states for loans. You can have a student who takes a break from school for less than six months, you can have a student who takes a break for longer than six months, you can have a student go back to school after being off for more than six months. You can have all sorts of states for a loan - current, behind 0-30 days, behind 31-60 days, and on and on.  

For this system the test data was crucial. We had to find test data or we had to create good test data from scratch. Delivering the user story with acceptance criteria and tests with test data was crucial for the team to be able to work uninterrupted within an iteration. It was hard, time consuming work. But we did it. We had to stick to a rigorous Definition of Ready before a user story could be planned into an iteration.

This gives you an example of moving from our 1-liner and paragraph to a 1-pager or even multiple-pages. 

Next we'll look at other requirements related artifacts we can use to build understanding for the team and other interested stakeholders.

Modeling notation can be found at: www.uml.org