How to Write Better User Stories With Gherkins (Template Included)

User stories are an Agile technique of defining product functionality and requirements. They focus on telling a story for an action a user will take and what the expectation is when successful. The concept of user stories is widely used, but telling good stories can be quite difficult.

User stories have taken a bit of a hit in the last few years though, as they’re slight oversimplifications and lack empathy for the user.

Good news – there is a better way! They’re called gherkins, but unlike the pickle, they’re not here to sour up your life. (Unless you’re a pickle lover, I suppose!) 🥒

TL;DR

If you’re in a bit of a rush, here’s the TL;DR (although I would encourage you to keep reading to access the templates!)

• User stories focus on the user, not the product.
• Outline your personas to add context.
• Add empathy to your stories to understand actions and motivations.
• Gherkins: a better way of writing stories.
• Use gherkins to focus on outcomes, not just outputs.

What are user stories?

User stories are short, simple descriptions of a solution that your team has come up with, told from the perspective of the person who is playing out the interaction. They are part of a larger epic that describes the actual problem to be solved and why you’re solving it.

The operative word here is user, meaning a user story puts the focus on the user, not the product.

A user story usually focuses on three areas:

• As a (who)
• I want to (what)
• So that (why)

This is all usually followed by acceptance criteria, which define how you know if the interaction is successful.

Who: Using personas to outline user stories

If you have yet to define or understand your users, then you really shouldn’t be writing user stories. Start with some discovery first, map out a customer journey, and create relevant user personas that will help you define these stories further.

A persona can help you understand and provide context to the ‘who’ of the user story – in other words, who is conducting this interaction.

This is important as you will inevitably have different customer segments, roles, and permissions involved, so defining those interactions to cater to those different types of users is important.

What: User story interactions

The ‘what’ in a user story focuses on the interaction itself. The tricky thing here is to make sure that your “what” is focusing on what the user has to do, as opposed to what the user wants to do, and this is where the typical story template falls apart a little bit.

To add a bit of empathy to the story itself, it’s important to highlight how the user might feel when interacting with a particular action.

For example, no one wants to enter a complicated password with a capital letter, special characters, and a minimum length – but they know they should. In this case, it is something that the user is required to do.

Why: The reason for the user story action

The third part of the user story template is the ‘why’ – that is, why the user wants to (or is required to) carry out a particular action.

Returning to our previous example of entering passwords:

As an admin, I am required to create a complicated password, so that my account is secure.

We now understand the who, what, and why of the story – but there is an issue here. This is still lacking empathy and context because let’s be honest, nobody wants complicated passwords to be a requirement, but we all want secure accounts.

When testing this, the QA team would simply stop at checking if the password is secure, not whether the process was frustrating for the user.

Enter the Gherkin user story template

Gherkins are a way to add to user stories and give a full scenario that will help developers and testers understand both the outcome and the output of a particular user interaction.

1. Scenario — the behavior you’re going to describe
2. Given — the beginning state of the scenario
3. When — a specific action that the user takes
4. Then — a testable outcome, usually caused by the action in When
5. And — this continues any of the other three operations if necessary

Taking the password scenario previously described:

1. When setting a password (Scenario),
2. Given that I am an account admin,
3. WhenI enter a password in the password field,
4. ThenI should be warned of the password requirements,
5. And I should be allowed to make corrections right away,
6. Then that I can create a secure account.

We now have a full picture of who is carrying out the specific action, and what the requirements are for the acceptance criteria, and the team knows what potential frustrations there might be so that they can ensure that the process flows more smoothly.

Generally, the product manager or product owner is responsible for writing out the Gherkin stories, thus creating better communication between the rest of the team and making sure that everyone is focusing on outcomes, not just outputs.

What are your favorite ways of outlining stories? Let me know! ✌️