Don’t Get Stuck: Using Gherkin to make sure your users don’t get lost
As a kid, I spent a vast amount time playing Theme Park, a fun but fairly basic strategy game and early forerunner to the more successful Roller Coaster Tycoon series. As with most strategy games, Theme Park came equipped with a know-it-all advisor who would regularly chastise you for all manner of park-related shortcomings, including one in particular which would pop up time and time again; ‘due to your poor park planning, one of your visitors has gotten stuck’. This would invariably lead to hours of trying to find a way to get them ‘unstuck’ (or simply ignoring them in the hopes that they would just disappear).
Fast forward twenty years and ensuring people ‘don’t get stuck’ is now a key part of my day job. Planning the user journey, use cases and user scenarios are of course all an important part of helping to deliver a frictionless user experience. Providing all of this information in a way which is accessible to stakeholders and development teams alike has proved a somewhat iterative process for me. In particular, use cases — describing how a feature works when users perform tasks— have been especially tricky to document.
Over the last few years, I’ve seen a myriad of ways to document use cases and found them to vary significantly in terms of success. On advice from a colleague, I ended up adopting the use of Gherkin language for my use cases and have found it to be a pretty bullet proof way of providing the documentation I need.
What is Gherkin language anyway?
For those who are wondering what the hell I’m on about, Gherkin language can be described best like this:
“Gherkin… is a Business Readable, Domain Specific Language that lets you describe software’s behaviour without detailing how that behaviour is implemented. Gherkin serves two purposes — documentation and automated tests.”
As the quote above — taken from the Cucumber wiki page on Github — suggests, Gherkin is a great language for documenting how a feature would work in the real world. The way I use it for writing User Experience documentation may deviate a little from the theoretical practice of writing use cases, but I find using Gherkin a wonderfully useful way of ensuring users don’t end up running down a dead end.
How do I write use cases using Gherkin?
The beauty of using Gherkin lies in the simplicity of its syntax. It follows a very simple Given/When/Then formula which easily translates to near enough every use case. I’ve provided an example below which hopefully demonstrates this fairly clearly.
I find writing in this way removes the ambiguity of language and the dreaded ‘curse of knowledge’ which people often succumb to when collaborating across departments. It allows everyone to get on the same page using simple phrases and terminology which follow a logical structure.
Writing use cases using Gherkin language has been a huge benefit, not only in ensuring that all edge cases and potential errors are accounted for, but also in describing real world bugs to developers in a common language, which is comfortable for all to understand and interpret.
It is a great way to formalise use cases in such a way that it demands that you think more carefully about what each function does, what it’s supposed to do when it’s working and what happens when it doesn’t work. In short, it’s much more difficult to leave your visitors stuck in your park with no hope of escaping due to your poor planning!
