How We Structured Our Requirements

A write-up of how we structured things in a previously somewhat disorganized project with requirements in several different formats and poor correlation between them and our test cases. The politics of why it was like that to begin with is outside the scope of this post.

Disclaimer: I have never worked extensively with user stories before this project so my experience is limited and our usage of terms may differ from "industry standards".

The Basic Structure

We have three basic artifacts:

• Story: a user story, very specific about something the user wishes to do or be done.
• Epic: a collection of user stories based on some common functionality.
• Saga: a short saga that sets the context of a specific situation of a specific user.

Our user story follows the basic pattern of:

"As a role, I want goal/desire so that benefit/value".

Each story was in the end verifiable either through automated tests or user acceptance tests.

Sagas and epics are orthogonal to each other. In a table or matrix one axis would be the sagas and the other axis would be the epics, and each cell would be a story.

An epic collects user stories surrounding a given function, e.g. "log-in", possibly from more than one role/stakeholder. Log-in for the end user should be easy, but from the system owner's point of view it must be secure.

A saga collects user stories from the viewpoint of a given user/role and situation. It gives focus on and increases understanding for a specific user, ensuring that the project team understands the user's daily life to avoid overlooking something obvious. A saga may collect user stories from many different epics into a single situation.

Example

Saga: Check e-mail at home

Jane User: At home I sit in my couch in front of the TV and during commercial breaks I want to check my e-mail on my phone. I usually don't write replies from the couch because I prefer a real keyboard for typing. I'm usually interested in doing the following:

1. logging in (if not already)
2. fetching any new e-mails
3. seeing a list (or similar) of new e-mails
4. picking a new (or old) e-mail to read
5. reading an e-mail

Epic: log-in

• Cache username
• Hide password
• Secure communication

Stories:

• As a user I want my username to be cached so I don't have to re-write it every time.
• As a user I want my password to be hidden so that the creepy fellow trying to read over my shoulder doesn't see it.
• As a system admin I want log-in communication to be encrypted so hostile entities don't sniff credentials.

Results and Discussion

In the end this setup worked out pretty well for us. Due to geographically distributed teams from various different companies and few common tools we ended up with a shared spreadsheet (lowest common denominator), sagas on one page and stories (with an epic column) on another page.

We only wrote sagas for our main user role since the project was a new frontend for that role, but in other cases it would probably benefit to write them for several different roles.

Have you done something similar? Would you have done something different? Do you see any improvements we could make on this structure? Please share your thoughts.