Jake Worth

• agile

When I am preparing development work, I write Gherkin-style stories, which follow the “Given/When/Then” format.

I learned this technique at Hashrocket and have practiced it ever since. It is incredibly effective. But why? In this post, I’ll try to answer that question.

I can think of two arguments for this technique: words and images hide complexity, while stories expose complexity.

Words and Images Hide Complexity

Words and images hide complexity.

When I’ve worked on teams that don’t widely use Gherkin syntax, we encounter a different version of this problem again and again:

“I finished the story and shipped it to QA, but then I noticed this one little thing I missed in the story. I’m working on that now.”

That little thing is often not little. It might be a major change in functionality, an important use case, or a key requirement from a stakeholder that blocks shipping.

This is rework, and rework is bad. Why do these details, that were written in the story, get missed? Because words hide complexity.

Here’s an example of part of a story, from a ticket:

“Then when they finish filling out the form, if they’re a new customer, they’ll be redirected to the welcome page, and if they’re an existing customer, they’ll be redirected to their dashboard. Unless they’ve come from our holiday marketing page– always send those people to the refer-a-friend page.”

There is so much complexity hiding this paragraph, three stories at least! Most tickets I’ve seen contain multiple paragraphs like this. They omit information, duplicate information, and contradict themselves. That’s how brain dumps work.

Images are even higher bandwidth than stories and can be even more confusing. Put two developers, a designer, and a stakeholder in front of some wireframes and ask them to describe what a page does; it’s amazing how many disagreements can arise.

Stories Reveal Complexity

So, what’s the solution? Gherkin stories. Stories reveal complexity. The format ensures that complexity has nowhere to hide.

Let’s take our previous wall of text and turn it into stories.

“Then when they finish filling out the form, if they’re a new customer, they’ll be redirected to the welcome page, and if they’re an existing customer, they’ll be redirected to their dashboard. Unless they’ve come from our holiday marketing page– always send those people to the refer-a-friend page.”

Where does this feature even start? We ask the question and learn that it starts on the checkout page.

Given I am on the checkout page

Now we can fill out the form we were filling out:

Given I am on the checkout page
When I finish filling out the form

Pause; what does “finish filling out the form” mean? Are we clicking submit, blurring a field, or leaving the page? We clarify with the stakeholder: the customer is submitting the form with a button, so we add that detail.

Given I am on the checkout page
When I fill out the form completely
And I click "Pay Now"

We’re already a little bit clearer.

Here’s where we get to our three-way-fork: some customers are redirected to the welcome page, some to the dashboard, and some to the refer-a-friend page. There’s no ‘if’ or ‘or’ keywords in Gherkin. If you find yourself using one, you need another story.

We need to break our story into three.

### New Customer Completes Checkout

Given I am a new customer
And I am on the checkout page
When I fill out the form completely
And I click "Pay Now"
Then I see the welcome page

### Existing Customer Completes Checkout

Given I am an existing customer
And I am on the checkout page
When I fill out the form completely
And I click "Pay Now"
Then I see my dashboard

### Referred Customer Completes Checkout

Given I am a new customer coming from the holiday marketing page
And I am on the checkout page
When I fill out the form completely
And I click "Pay Now"
Then I see the refer-a-friend page

What’s happening here? We’re translating a wall of text into three deliverable units of work. It’s more words, sure, but that’s the point– this is three stories! They might be small, but they aren’t the same experience.

Because we wrote these stories, the developer who is going to implement them is starting off knowing that they need to track whether the customer is new or returning, and which page they may have been referred from. The QA tester who tests the story is better off too, because they have three pre-written checklists to follow telling them exactly what success or failure means.

Write Stories!

I have yet to see an alternative to this approach that works for a team. You can get by without stories with one or two developers, but soon you are going to need them because nobody can know everything that’s going on.

What are your thoughts on Gherkin stories? Let me know!