Telling a Story with a User Story

By Greg Horsfall, Senior Business Analyst at Nimble Approach

Everyone has their own way of approaching User Stories, whether it’s following a structure like Gherkin, or something they’ve adapted over the creation of hundreds of user stories, having worked with different teams. And this is my own approach and why I recommend it to everyone…

A typical User Story

1. As a <user>
2. I want <to be able to..>
3. So that <a reason..>

But let’s have a look at a couple of the “standard” User Story structures and overall makeup.

“One Size Fits All”

This is what most people define as being the “Story” portion of a User Story and it follows a fairly standard template:

It’s a short form and simple description of a feature from the perspective of a person (or possibly a system) that desires a new or altered capability.

Personally I have two problems with using this template. Firstly, one size might fit all, but does everyone really want to be wearing pink jogging bottoms with “Juicy” spelled out in sequins across the buttocks? Whilst having a standardised structure supports readability and understanding from stakeholders (including the team), it doesn’t always fit the need being captured in the User Story, and it misses so much context.

Here’s an example:

Whilst it defines the functionality, it doesn’t give any context for the underlying infrastructure and it loses its value to the individuals who are expected to deliver against the User Story. This usually leads towards Technical Stories that are written in plain English with a list of technical requirements captured in the acceptance criteria.

And this brings me to my second problem with the “one size fits all” User Story structure. As soon as the developers don’t get the information they need from the User Story and they just look at the list in the acceptance criteria, who are you writing the User Story for? The title of the index card, Jira ticket or any other tool should give stakeholders from outside of the team the information they need about what will be delivered, so the “As a <user of some kind>, I want <to be able to do something or a goal>, so that <a reason for wanting to be able to do something>.” is wasted effort by the Product Owner/Product Manager/Business Analyst.

Acceptance Criteria – hold the Gherkin

Cucumber is actually a tool that supports automated software tests in an easy to write and easy to read format. So if Cucumber is an automated software tool rather than an approach for writing User Stories, why am I bringing it up?

Well for a development team to know when they’ve completed a User Story, they need acceptance criteria (the conditions that a product or feature must satisfy to be accepted by the end user), and when using Cucumber, those acceptance criteria are often captured as specific testing scenarios. And that is where Gherkin comes in.

Gherkin is a Domain Specific Language for writing acceptance criteria using four to five main statements:

1. Scenario – this is the title for this particular acceptance criteria, it should act as an easy to identify and understand label for what is described in the remaining statements.
2. Given – this is the setup, the situation, the state that you or the software has to be in for the remaining statements to take place.
3. When – this is the trigger for the test scenario, often a specific action that a user takes, but it could be a time trigger or an action by another system.
4. Then – this is a testable outcome of the trigger, so when something happens, then this is the result.
5. And – in some instances, the then leads onto something else, or there may be other qualifying statements. In these instances “And” can be used to include additional “Given”, “When” and “Then” statements.

Example Scenario:

User navigates to the ‘contact us‘ page from and ‘blog‘ page.

Given I’m reading this ‘blog‘ post, when I click the ‘contact us‘ link at the top of the page,

Then the ‘contact us‘ page should load.

Gherkin acceptance criteria can then be translated into code that can be used as part of automated testing. But depending on the software you’re working on, there may be dozens of qualifying statements, something that can cause a User Story to really spiral out of control, resulting in several test scripts written by someone who isn’t a tester (usually the Product Owner) making up the majority of the Jira ticket.

My Own Approach to User Stories

So what I said at the start was a bit of a lie, this isn’t “my own approach”, because there is no single approach that I use there are just two guiding principles. These guiding principles are all too often overlooked to the detriment of everyone involved in the process from the sponsor and the product manager to the delivery team and the end user.

Principle 1 – Know your target audience

When writing User Stories, it can be easy to get caught up in the process and thinking that your target audience is the same as your end user. I’m here to tell you that is not the case.

As the author of User Stories, your target audience is anyone who is going to read those User Stories and derive understanding or is expected to create something based on the content of the User Story. In most cases, your target audience will be your delivery team and possibly your stakeholders.

This might not sounds revolutionary but if it’s nothing new to you, why are you still writing “As a <…>, I want <…>, so that <…>” for Technical Stories?

My advice for anyone writing user stories, whether you’ve been working with the delivery team for years or have just started is to ask them exactly what information they want to see. The same goes for your stakeholders. If they are engaged with reading the User Stories, seeing a technical breakdown of what system needs to be updated may not mean anything to them.

This could result in having two distinct sections within every user story, something that helps the delivery team to understand what work needs to be done, and something to help your less technical stakeholders understand the value in delivering what is in the User Story.

As a word of warning, this doesn’t mean that you should do the jobs of the delivery team in identifying how things should be delivered (e.g. transform the XML message into JSON using JOLT). The delivery team are still the best people for doing the job and the purpose of the User Story is to tell them WHAT needs to be done, not HOW it should be done.

This (in my opinion) also applies to writing acceptance criteria using Gherkin. As long as you can communicate WHAT needs to be delivered, the test scripts should be defined by the best people for the job (i.e. anyone in the delivery team providing quality assurance). That isn’t to say that Acceptance Criteria shouldn’t be written as part of writing User Stories, just that I don’t think they should be written using Gherkin by the Product Owner.

Principle 2 – Don’t forget the Story

I suppose this is the real intention behind the “As a <…>, I want <…>, so that <…>” structure, but all too often I see ineffective User Stories because they have been forced into that structure without understanding the intention. If you can tell a story with your User Story (I know, revolutionary right!?) it will help anyone reading it. You shouldn’t write a novel for every deliverable, but giving your delivery team something to understand the content, the reason and the value that will be achieved for your end users will drastically improve communication within the team.

There are additional benefits to this as well. If the delivery team understand the intention behind the User Story, they might be able to identify additional acceptance criteria, edges cases or entirely new requirements that you hadn’t considered yourself.

I’m not going to go into the details of how stories sell, or how to write effective stories as I think I’ve taken up enough of your time, but keep in mind the first principle when writing your stories.

Summary

How you write your user stories is entirely up to you, if you want to use  “As a <…>, I want <…>, so that <…>”, and personally write every test script related to the User Story as Gherkin acceptance criteria, that is your choice. But I urge you to ask yourself whether something adds value to your target audience, and does it give your target audience an understanding of the value created for your end users so that they can make insights and decisions to create the best possible output?