PM Tips - Improving My User Story Acceptance Criteria
A lot has changed since I last wrote a post. I've started a new Product role at Pivotal Labs. I've also been building small Rails apps now that I've completed the Agile Development Using Ruby on Rails (ADUROR) course* on edx. Iâm thankful that my new job began right at the completion of the ADUROR course because many of the practices recommended by the course were modeled after how my current company works. The course put strong emphasis on how behavior driven development and test driven development can be used together to create software solutions in a world of uncertainty. To do this effectively, it is recommended that you write customer-friendly user stories with acceptance criteria in the Gherkin language. I was familiar with the customer-friendly user story portion but the Gherkin acceptance criteria was new to me and I would like to share what I learned about that particular portion of the user story.Â
So what exactly goes into Gherkin Acceptance Criteria? Let's create a hypothetical user story that we can use for the rest of this breakdown to explain the components. Let's imagine you are in the early stages of building an app that tracks ice cream trucks so that you know how far away they are and can plan for their arrival (since those quarters wonât round up themselves). The app is in the app store and users have started providing feedback that they want the ability to save their favorite icecream trucks so that they can differentiate them from the other trucks on the map. Youâve performed some research on this idea and have validated that this would be a valuable feature.
Hereâs how to approach creating the user story. First, you can write the traditional user story, where you explain the user value this feature provides. This is the standard "As a____, I want to ____, so that ____â format. If Job Stories are more your speed feel free to substitute in a job story.
In our example, the user story would be:Â
As a user, I want to save favorite icecream trucks, so that I can see a heart marker that differentiates my favorite trucks from the other trucks on the map
Next you can write the Gherkin acceptance criteria. This section should play out like a well-written movie. The scenario is clear, the action occurs, and then there are results based on the action. You want to explain the scenario by starting with âGIVEN." Next you want to explain the action by  starting with âWHEN." Lastly you explain the result by starting with âTHEN."  If you want to elaborate on any sections you can add âAND" to provide additional information. Letâs put it all together for the user story weâve been building:
Given I am logged in
And I have visited the âMap Screenâ
When I click the âfavorite" button next to âMr.Swirlyâsâ name in the truck listÂ
Then I should see a âfavorite heart" icon above Mr. Swirlyâs truck on the map
From a Development perspective, Iâve found the benefit of writing Gherkin acceptance criteria is I have to really understand the full user experience for a story prior to writing a single line of code. From a Product standpoint, writing Gherkin acceptance criteria forces me to clearly outline the scenario, user actions, and results that users see in response to their actions. I used to write acceptance criteria for a QA team in the form of a checklist of items that must be verified in order for a story to be ready for acceptance. I see much more value in explaining acceptance criteria in a way that a test suite can validate and working in a process where the tests are written prior to the user story being developed. The creation of the tests prior to the code ensures that there is clarity about what success means and there are constant checks of new features against old tests to ensure nothing has been broken. This leads to better code quality and a more stable user experience. QA can co-exist with this way of working if thatâs a role within your company. This introduces more time for the QA team to focus on use cases that have not been covered by automated testing, traffic surges, and device variations. Iâve found that writing Gherkin acceptance criteria has had the unexpected benefit of leading to more clarity, not just for computers, but also for people who are manually reviewing a story for acceptance.
Writing user stories may seem like a tiny part of being a product manager so it can be easy to rush through them but they are extremely important. Writing clear, thought-out stories can lead to a lower story rejection rate which will hopefully lead to a higher velocity. The result is also a higher quality application for the end user. I challenge you to approach your stories the way SaltBae approaches cookingâ with care and precision.
Do you write your user stories differently and want to share your best practices with me? Please reach out to me using the links to the upper left. I would love to hear about your personal experience with user stories. Are you curious about trying the format I just described in your next stories? Let me know how it goes and if you run into any issues.
*Note- The course I mentioned above is âAgile Development Using Ruby on Rails (ADUROR)â on edx.