Spring Cleaning: Belvedere’s Take on User Stories

Years and firms ago when I started off as a Business Analyst, I would spend weeks writing highly detailed software requirements specifications. I created documents with hundreds of pages containing every detail of the software product we were about to build. I had everything in there. Screen mockups with callouts for every single field. Any possible scenario that a user might encounter. Detailed descriptions of desired behavior. "The system shall do this..." and "The system shall do that..."

They were works of art.

The only problem? No one ever read them.

It should not have surprised me that no one slogged through page after page of dense text. It is the nature of developers to read as little as possible and code as quickly as allowed. Devs wanted to rapidly understand what I wanted and then go off to build it. I wanted the same thing, but the lengthy documents were not delivering their much hoped-for result.

User stories came to the rescue!!!

At Belvedere, we have embraced Agile to roll out our code, yet almost all new team members struggle when writing his or her first batch of user stories. This is not at all uncommon: just like riding a bike, it does take a little bit of practice (but once you get it – you get it).


What is a user story?

A user story represents a small piece of business value that a team can deliver in a sprint, which at BT is two weeks.  Additional details are provided in the form of a checklist called acceptance criteria. This approach succinctly allows the team to understand what the end-user, most often a trader, wants.

Here are three great articles on user stories:

The Essential Guide to User Story Creation for Agile Leaders

User Story Heuristics: Understanding Agile Requirements

How to Write Great Agile User Stories


What’s unique about user stories at Belvedere?

Belvedere has tailored the format of user stories to provide more emphasis on business value rather than the user role.

This is the conventional format for user stories:

As a <type of user> I want <some functionality> so that <some benefit>.


Whereas this is how we frame stories at Belvedere:

In order to <business value>, as a <user type> I want <goals>.

Here is an example of a trader facing user story:

In order to view at which exchange the trade occured
as a trader,
I want to include an "exchange" column in the report.

In the above example, the business value of viewing at which exchange the trade occurred is stated first. Clearly distilling this immediately helps our Business Analysts (BAs) and Product Owners (POs) to prioritize the most important stories for upcoming sprint.

While the Agile methodology encourages writing user stories for front-end systems, we also write user stories for technical requirements. We have found at BT that this improves prioritization and visibility of technical debt projects. The BA is primarily responsible for gathering the requirements from the traders and creating user stories. However, for technical user stories, developers sometimes wear the BA hat to help draft user stories. This has improved team creativity, collaboration and effectiveness greatly.

 Here is an example of a technical user story:

 In order to test Nagios changes,
as a Release Manager,
I want a working Nagios Vagrant Box.


Automation for better requirement traceability

Belvedere uses some powerful tools such as Redmine, Gerrit, and TestRail to help track the lifecycle of user stories from inception to deployment. We have spoken about Gerrit in our previous articles which you can find here.  This article will mainly focus on Redmine and its integration with Gerrit and TestRail. BAs and POs use Redmine extensively for prioritization and estimation of user stories to capturing detailed requirements and acceptance criteria for the user story and thereafter tracking the progress of the story in terms of implementation, testing, and final deployment. Gerrit and TestRail are well integrated with Redmine so when Devs and QAs use them to push up commits and create/execute test plans respectively, the status of the user story is automatically updated in Redmine to reflect the current state of the user story.

Now, let’s go over an example of a user story that is created in Redmine and how we track the progress of the user story throughout it's life cycle.


Step 1: User story created in Redmine and story pointed. Status changed to "Todo"

Step 2: Dev pushes up the code for the user story in Gerrit and specifies the RedmineID in the commit title. A unique GerritID is generated. Clicking on the RedmineID will automatically open the user story.

Step 3: The status of the user story in Redmine is changed from "Todo" to "InProgress" to indicate that it is currently in coding. A task is autogenerated and linked to the user story that ties the Gerrit commit to the user story in Redmine.

Step 4: QA also creates a testplan for the user story in TestRail and specifies the user story and the Gerrit commits in the test plan. This activity happens while the Devs are coding in parallel. 

Step 5:  When the Gerrit commit is ready for code review and functional review, the Team Lead and BA sign off (+1 or -1) on the commit respectively.

Step 6:  Redmine automatically updates the status of the user story status from "In Progress" to Ready to Test". From this point onwards, BA manually updates the status of the user story in Redmine.

Step 7:  QA will execute the tests cases in TestRail and if all the tests pass, QA signs off in TestRail which will automatically sign off the QA approval in the Gerrit commit. 

Step 8: The Gerrit commit requires additional approvals such as build and unit test sign off (automatically done by Jenkins) , deployment sign off by Release team before it is ready for merge. Once the Gerrit commit is merged, BA moves the status of the user story to "Merged".

Step 9:  Once the Gerrit commit is deployed, an automatic email is sent out to the tech department indicating which commits were deployed. BA moves the status of the user story to "Deployed". This is done to ensure that BA follows up on the deployment to make sure everything was deployed correctly.

Step 10:  BA follows up with the PO and the trader that requested the user story to confirm that it is working as expected before closing it out.

In summary…

User stories allow you to rapidly capture the requirements of your project and create specifications in a format that is easily digestible for your team. A side benefit of this approach is the ability to collaborate not only with your team, but across departments to create the stories. The format is simple and any team member can understand and immediately contribute ideas in template form. Firm-wide, traders and developers alike can understand the end goal and generate solutions to reach it.