TUTUSTU mitä me osaamme ja teemme
TUTUSTU mitä me osaamme ja teemme



Ota yhteyttä

KAHVIA VAI TEETÄ? Piipahda luonamme.

elokuuta 14, 2017

How we structured our requirements

This is a write up of how we structured our requirements in a project last year. This was the first time we'd tried the "user story" format for our requirements. We feel it turned out pretty well with an easy to overview structure that was easy to correlate to test activities and didn't allow for big things to fall between the cracks.

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.


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

Collects the following user stories:

  • Cache Username
  • Hide Password
  • Secure Communication


  • Cache Username: As a user I want my username to be cached so I don't have to re-write it every time.
  • Hide Password: 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.
  • Secure Communication: As a system admin I want log-in communication to be encrypted so hostile entities don't sniff credentials.


As mentioned previously we thought this setup worked out well for us. We also found that taking this structure and summarizing it in for example a spreadsheet for the steering committee was really easy: 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 with us @EnfoGroup using the hashtag #itsallaboutintegration


Rasmus Larsson

Senior Integration Architect