8 minute read · Published March 27, 2024

Tame the complex tech talk – how Gherkin user stories show that natural language wins

Latest Update March 27, 2024

Imagine life without tech platforms. No online banking apps to keep your finances in check. No cloud collaboration for those epic document battles with colleagues. Even the seemingly simple tasks, like scheduling doctor appointments or ordering groceries, would be a logistical nightmare. 

Ok maybe this is a modern-day problem (humans did just fine without all these things for centuries!) 

But, there are countless ways in which we, as users, interact with the platforms and apps that have become ingrained in our lives. You're interacting with some form of technological solution even when you don’t realize it. Like reading this article on your screen. 

Folks in SaaS product management constantly strive to keep pace with user demands, whether it's developing entirely new features or enhancing existing ones. It can be a challenge to bridge the gap between user needs and technical realities.

This is where Gherkin steps in. It provides a framework for clear stakeholder communication, allowing SaaS businesses to translate the needs of their users into relevant features and agile development. Ultimately, this leads to building a product that is loved and advocated for by its users.

Understanding Gherkin

At the core of every software product lies a common mission – to help users achieve something specific. Whether it's conquering their to-do list, designing a jaw-dropping presentation, or mastering the art of collaboration with their teams to create a single source of truth for all their projects, users have specific goals in mind when they use an app.

For this reason, user stories are designed to articulate the “needs” or “demands” of users. These are then translated by code into features. 

Traditional user story vs. Gherkin user story

Imagine you're building a photo-sharing app. Both traditional user stories and Gherkin user stories can help capture user needs, but they do it in very different ways.

A traditional user story would collect software requirements and say, "As a user, I want to be able to add funny effects to my photos, so that my posts are more engaging and get more likes."

Such a story gives a general idea – users want to add funny effects. However, it lacks specifics. 

It doesn't tell us:

  • What kind of "funny effects" users have in mind? Are we talking silly filters, wacky distortions, or something more creative?
  • How do users want to add these effects? Do they want a simple one-click solution or more control over the editing process?
  • What kind of results should they see?

Such lack of detail can lead to misunderstandings during development. Imagine developers spending weeks, or worse, months, building a complex photo editing suite when users just wanted a few silly filters they could use with a single click.

The Gherkin approach is a step-by-step guide from “desire" to “outcome”. A Gherkin user story goes like this:

Scenario: Enhance photo with fun filters 

Given: I am creating a new post on the social media app and have selected a photo to upload 

When: I select the "Edit" menu and choose the "Filters" option 

Then: I should see a variety of fun filters available (e.g., cat face, dog ears, bunny nose, sparkly effects) 

And: When I select a specific filter, it should be applied to my photo in a visually appealing way 

And: I should be able to preview the filtered photo before saving or posting it

 Image visually represents the key components of a Gherkin user story, such as Given, When, Then

With Gherkin, everyone’s on the same page – that’s how clear the story is. Developers understand what kind of filters users want, designers can create an intuitive editing experience, and the product team can measure success based on filter usage and user engagement. No more misunderstandings, just a clear path to creating features that users will love.

Why does Gherkin matter in SaaS Product Management?

Product owners are passionate about user needs, developers are laser-focused on code, and testers are all about finding bugs. While their goals are intertwined, it can sometimes feel like they're speaking different languages. 

Imagine this conversation taking place in the previous example:

  • Product owner: "Users crave engagement! We need to make photos pop!"
  • Developer: (confused look) "Pop? Like, a pop-up window?"
  • Tester: (concerned) "Pop-up windows are so 2000s! Are we sure...?"

This is definitely not a fun conversation. It’s frustrating, confusing, and a waste of precious development time. 

By using Gherkin, you can – 

  • Leverage a human-readable language: Gherkin uses everyday words to describe user stories, translating complex functionalities into clear, concise language. No more explaining what words like "API integrations" or "backend processes” mean to non-technical teams.  
  • Focus on the user journey: Instead of getting bogged down in technical details, Gherkin guides everyone to focus on the user's perspective. Imagine your marketing team suggesting a feature that lets users personalize their profiles with "epic win" gifs after completing tasks. Gherkin helps translate this quirky idea into a user story that outlines how the feature would work and how it benefits users (increased satisfaction, maybe a boost in productivity, or perhaps a boost of serotonin).
  • Drive shared vision and shared success: With Gherkin, everyone has a clear understanding of the software's goals. Tech teams can explain features in a way that's relevant to the user experience, while your marketing team can visualize how these features will translate into engaging campaigns and a happy user base (think "epic win" gif campaign for power users).  

Demystifying Gherkin & behavior-driven development

Imagine behavior-driven development (BDD) as a collaborative workshop. It brings together your entire team – developers, designers, product managers, and other stakeholders – to focus on one crucial aspect – how will users interact with your software. These are brainstorming sessions fuelled by user needs and real-world scenarios.

Image showcases the key benefits of using Gherkin in software development

During BDD workshops, the team identifies specific user behaviors and translates them into clear, actionable steps. There are several benefits to this – 

  • Everyone speaks the same language (plain English), leading to fewer misunderstandings and a smoother development process. Nothing is open to individual interpretation. 
  • BDD prioritizes features based on their value to the user, ensuring development resources are directed towards functionalities that deliver the most impact, thus supporting agile development.
  • Gherkin scenarios can be easily converted into automated tests, leading to higher-quality software and easier maintenance down the road.

Crafting compelling Gherkin user stories 

Consider these best practices when writing Gherkin user stories: 

  • Focus on user behavior: Keep the user at the center of your scenarios. Describe the "who" and "what" of a feature from the user's perspective.
  • Structure matters: Utilize the core Gherkin keywords ("Given," "When," "Then") effectively to define the context, user action, and expected outcome.
  • Clarity is key: Use concise and clear language. Avoid technical jargon and ensure everyone involved can understand the scenario.
  • Keep it specific: Don't be vague. Define specific user actions, data points, and expected results.
  • Break down complex features: For complex functionalities, consider creating multiple Gherkin scenarios that break down the user flow into smaller, more manageable steps.
  • Examples are powerful: Don't be afraid to use examples within your scenarios to further illustrate user actions and expected outcomes.

For instance, consider a user demand for an “app” that gamifies and rewards social media detox. Here’s how you could go about composing the Gherkin user story. 

  • Focus on user behavior: This scenario focuses on a user who wants to reduce their social media usage in a fun and engaging way.
  • Structure:

Scenario: Earn Points and Badges for Social Media Breaks

Given: I am a user who has signed up for the social media detox app and linked my social media accounts. (This sets the context: the user is registered and has connected their social media)

When: I close all my social media apps and remain inactive for a predetermined amount of time (e.g., 30 minutes)

Then: The app should detect that I am not using social media for the chosen duration. (Defines the user action and expected app response)

And: I should be awarded points for my social media break. (Defines a clear outcome and user benefit)

And: I should see a progress bar indicating how much time is left in my chosen break period. (Provides visual feedback to the user)

  • Clarity & specificity:

Points awarded should be a specific number or based on a clear point system within the app (e.g., 10 points per 30-minute break).

The type of social media inactivity can be clearly defined (e.g., no opening social media apps, no social media notifications interacted with).

  • Example: "As a user, if I close my Instagram and Facebook apps for 45 minutes, I should earn 15 points and see a notification congratulating me on reaching my halfway mark."

Fitting Gherkin in the SaaS development lifecycle

Gherkin isn't just about writing scenarios; it's about fostering collaboration throughout the entire development process. Here's how to integrate Gherkin effectively – 

  • During product discovery workshops, involve stakeholders in brainstorming user needs. Capture these needs as initial Gherkin user stories, focusing on the "what" and "why" of potential features.
  • Conduct BDD workshops where product owners, developers, and testers collaborate on refining Gherkin user stories. This ensures everyone understands the user perspective and desired functionality.
  • Use Gherkin scenarios for effort estimation. This allows product managers to prioritize features based on user value and development complexity for agile development.
  • Gherkin scenarios can be easily converted into automated tests. This streamlines the testing process and ensures the final product aligns with user stories.
  • Gather feedback on features throughout the development cycle. Refine Gherkin user stories based on this feedback to ensure continuous improvement.

Tools and platforms for a smoother behavior-driven development process

While Gherkin itself is a lightweight language, there are various tools and platforms that can enhance your BDD experience:

  • Cucumber: A popular open-source framework that supports Gherkin syntax and facilitates behavior-driven development practices. 
  • SpecFlow: A BDD framework specifically designed for the .NET development environment. 
  • Gherkin editor plugins: Integrate Gherkin syntax highlighting and autocompletion features into your favorite code editor for a more streamlined writing experience. (Available for various editors like Visual Studio Code and IntelliJ IDEA)
  • BDD reporting tools: These tools generate reports based on your Gherkin scenarios, providing insights into test coverage and overall project progress. (examples: Report Portal, testim.io)

The best tools for your SaaS development will depend on your specific needs and existing technology stack. Consider factors like team size, technical expertise, and desired functionalities when selecting tools to support your BDD journey with Gherkin.

Fuel collaboration with Gherkin

The beauty of Gherkin lies in its ability to transcend technical boundaries.

Image depicts a diverse team working together using Gherkin user stories

Here's how it fosters collaboration across diverse teams:

  • Gherkin user stories provide a common ground for product owners, developers, and testers. This breaks down communication silos and encourages open discussion about requirements.
  • Non-technical stakeholders can easily grasp Gherkin user stories, allowing them to provide valuable feedback and participate actively in the development process.
  • Gherkin scenarios serve as living documentation that evolves throughout the development process. This eliminates the need for lengthy, outdated documents that, let’s face it, often become cumbersome.

No development drama, just impactful deliveries 

User stories can leave your team scratching their heads. Gherkin acts as the "universal translator" for your dev team, ensuring everyone (from designers to product owners) speaks the same language.

  • Fills stakeholder communication gaps: No more misunderstandings or lost-in-translation moments. Gherkin's plain English keeps everyone on the same page.
  • Focuses on user value at all times: User needs become the North Star, guiding development and ensuring features deliver real value to your customers.
  • Breaks down silos faster than a falling pack of dominoes: BDD workshops create a collaborative environment where everyone plays a role. Think of it as the ultimate team-building exercise.
  • Boosts development speed like a rocket launch: Automated testing based on clear user stories streamlines the process, getting you to market faster.
  • Reduces defects: Well-defined scenarios mean fewer bugs and a more polished final product.

So you don't have to worry about development dramas, no matter how outlandish the user "demand" might seem. Gherkin user stories bridge the gap between even the most creative user requests and the realities of agile development. They ensure everyone involved is on the same page, allowing you to deliver true value to users.

Copy icon
X logo
LinkedIn logo
Email Icon

We are not accepting new subscribers at this time.

Join the waitlist

and we’ll see what we can do.

Continue Reading

Up Next

Harnessing the power of LangChain: A deep dive into five innovative projects

Read Now

What's hot