My Feature Writing Template: Given/When/Then

When preparing feature development work, I write Gherkin-style tickets, which follow the “Given/When/Then” format. Many people call these stories, and I do, too. This technique is incredibly effective! But why? In this post, I’ll try to answer that question.

I learned this technique watching the greats at Hashrocket. They’ve been doing it this way since 2008 because it works.

I have two complementary arguments for this technique: images and raw text hide complexity, while stories reveal complexity.

Images and Raw Text Hide Complexity

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

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

This “little thing” is often large. It might be a change to functionality, an important use case, or a missed requirement that blocks shipping.

Fixing it requires rework, something software engineers consider bad. So why did these details, that were written in the ticket, get missed? Because raw text hides complexity.

Here’s a part of that fateful 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! Many tickets I’ve seen contain multiple paragraphs like this. They omit information, duplicate information, and contradict themselves. That’s how our brains work when dumping information.

Images like screenshots or wireframes, without additional context, have even higher bandwidth than stories and can thus be even more confusing. Put two engineers, a designer, and a stakeholder in front of some wireframes and ask them to describe how a feature works. It’s amazing how many disagreements can arise.

Stories Reveal Complexity

What’s the solution? Gherkin stories. Stories reveal complexity. The format is designed so that complexity has nowhere to hide.

Let’s take our previous wall of text and turn it into stories. Here it is again:

“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 experience begin? What’s the first thing that a user sees? We ask a stakeholder the question and they respond that it starts on the checkout page. We have our first “Given” statement:

Given I am on the checkout page

What are they doing there? Filling out the form:

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 submit 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 quite a 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 are no ‘if’ or ‘or’ keywords in Gherkin by design. When 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

High-level, what’s happening here? We’re translating a wall of text into three simple, deliverable units of work.

Because we wrote these stories, the engineer who implements them starts off knowing that the code must track:

  1. Whether the customer is new or returning
  2. Which page they may have been referred from.

The QA tester is empowered, too, because they have three complete checklists to follow telling them precisely what success means.

Counterarguments

Let me address some counterarguments. The ones I can think of are: that it takes longer to write stories, that images and text can work, that it can be a difficult mental shift, and that the Gherkin syntax can be confusing or awkward.

Yes, these stories take a bit longer to write than a brain dump. But that’s the point– this was always three stories of complexity! Each one might be small, but they are unique user experiences. Isn’t it better that we’re acknowledging that?

What if I do a great job writing my text and building my wireframes; isn’t more information better? While I agree that communication is a virtue, the consumer of these tickets must be able to find the signal in the noise. Re-read through the Gherkin stories we wrote– we skipped past irrelevant parts of the experience like logging in and filling up the cart. We omitted implementation details, tech debt, historical baggage, etc. Gherkin stories are mostly signal.

If this way of thinking is difficult, stick with it! It’s a skill that can be learned. Along the way you’ll become more knowledgeable about the product and start thinking from a user-focused perspective.

Lastly, if you’re struggling with the Gherkin syntax, note that the keywords “Given/When/Then” are a convention. They can be swapped or replaced, and continued with “And.” Don’t get hung up on the syntax. Whatever makes the story read the best is what you should use.

You can survive without stories with one or two engineers, but as your team grows you’re going to need them, because at a certain small scale, it becomes almost impossible to know everything that’s going on. This is the best technique I’ve seen to communicate user experience at scale.