In a pickle actioning your GDD? Try Gherkin

Bridge design and development with clarity.

Podcast generated with Notebook LM.

• Gherkin syntax transforms abstract Game Design Documents into actionable, testable behaviours, fostering team alignment.

• Its plain English, behaviour-driven format reduces ambiguity and bridges gaps between design vision and implementation.

• While effective, Gherkin can introduce complexity, requiring careful adoption based on project needs and team capabilities.

The Gherkin syntax might be the hero we need to turn a Game Design Document (GDD) into something actionable for your team. We often miss a trick by waiting until after a GDD is complete to think about the user experience in practical, concrete ways. A GDD already has all the meat—the player goals, the features, the intricacies—but if we don’t translate that into executable chunks of work, it can get lost in translation between product managers, designers and developers.

A GDD is like a beautiful painting—it captures the idea perfectly for producers, developers, and designers. But it’s an idea that can often be too abstract when the rubber hits the road, especially for live-game services where rapid iteration and flexibility are essential. We all know what happens: a feature gets scoped, assumptions evolve, or constraints rear their ugly heads, and suddenly, the GDD isn’t as relevant as it used to be. Yet, without a clear path to keep everyone aligned, the fallout often hits the QA teams hardest—they’re testing something that might not even match the final scope anymore.

This is where Gherkin shines. It helps you take that GDD and break it down into actual, tangible behaviours using plain English—something anyone on the team, from marketing to development, can understand.

What is Gherkin and How Was It Created?

Gherkin is a business-readable, domain-specific language that allows you to describe software behaviours without digging into the technical details of coding. It was designed to be easy to understand for technical and non-technical stakeholders, ensuring that everyone involved in the development process can follow along. The syntax is straightforward and written in plain English, often structured in a Given-When-Then format, which makes it particularly effective for Behaviour-Driven Development (BDD).

The concept behind Gherkin was created as part of the Cucumber project, initiated by Aslak Hellesøy in 2008. The goal of Cucumber—and Gherkin, by extension—was to bridge the communication gap between business stakeholders and the development team. The intention was to create a common language that everyone could use to specify system behaviours, thus fostering collaboration and reducing misunderstandings.

Gherkin is a tool for describing features and functions as a basis for automated testing. Each line of Gherkin corresponds to an action or expectation, which can then be connected to code that tests whether the described behaviour is working as expected. This means that Gherkin can serve as both documentation and executable specifications, enabling development teams to immediately ensure features meet the intended requirements.

In practice, Gherkin provides a simple and effective way to describe how a feature should behave, making it accessible to anyone—whether they’re from QA, product, development, or even marketing. It turns abstract requirements into concrete, easy-to-understand, discuss, and test scenarios. Forget writing up new user stories; use Gherkin to describe the scenarios directly from the GDD. It turns your features into behaviours and establishes a clear line of sight for your developers and testers. This is especially handy in live-game situations where clarity and flexibility are non-negotiable.

So, instead of starting from scratch or getting stuck in Jira, look at the GDD through the lens of player behaviour. With Gherkin, you describe scenarios such as “When a player runs out of lives, they are offered an option to watch an ad for more.” This way, the GDD’s vision gets broken into understandable chunks—more importantly, they’re actionable. Not only does it reduce the ambiguity that can haunt big features, but it also provides a shared understanding that the whole team can rally around.

Gherkin Syntax Explained

Gherkin syntax is designed to be simple, straightforward, and accessible. It uses a structured format with keywords such as Feature, Scenario, Given, When, Then, And, and But. Each of these keywords plays a specific role in defining the behaviour of a feature in plain language, ensuring that the scenarios are easy to follow for both technical and non-technical stakeholders.

The Given-When-Then structure helps in defining the scenario clearly:

• Given represents the context of the system.

• When describes the action taken by the user or system.

• Then outlines the expected result of that action.

Here’s a detailed breakdown of the Gherkin syntax elements:

• Feature: This keyword introduces a feature or a functionality of the application. It provides a high-level description of what the feature is about. For example:

Feature: Player Inventory Management
  This feature allows players to manage items in their inventory, including adding, removing, and viewing items.

• Scenario: Scenarios describe individual behaviours or actions within a feature. Each scenario should represent a single path through the feature, describing a specific aspect of how users will interact with it. For example:

Scenario: Adding an item to the inventory

• Given: This keyword sets the initial context or the preconditions for the scenario. It describes the state of the system before any actions are taken. For example:

Given the player has logged into the game

• When: This keyword specifies the action or event that triggers the behaviour being described. It is the step that a user or system takes. For example:

When the player adds an item to their inventory

• Then: This keyword defines the expected outcome after the action has taken place. It describes how the system should behave in response to the When condition. For example:

Then the item should be visible in the player's inventory

• And/But: These keywords are used to add additional steps within a Given, When, or Then block. They help to extend scenarios without repeating keywords, keeping the language concise and readable. For example:

And the inventory count should increase by one

Each Gherkin scenario is meant to be concise and focused, representing one particular use case or user journey. This simplicity allows developers and stakeholders to understand the intended behaviour without any technical background. Standardising syntax across projects also promotes consistency, making it easier to maintain and scale.

---

My Product Owner is a Robot: Using ChatGPT to Create User Stories

---

Real World Example

Here is the feature description from the original GTA GDD from 1995, when it was called ‘Race ‘n Chase’.

5.5 Actions- Players will be able to drive cars and possibly other vehicles such as boats, helicopters, or lorries. Cars can be stolen, raced, collided, crashed (ram-raiding?), and have to be navigated about a large map. It will also be possible for players to get out of their car and steal another one. This will mean controlling a vulnerable pedestrian for a short time. Trying to steal a car may result in an alarm being set off which will, of course, alert the police.

Now, here is that feature decomposed in Gherkin for the player and NPCs:

Feature: Player Actions and NPC Behaviors

  Scenario: Operating Various Vehicles
    Given the player is in the game world
    When the player wants to operate a vehicle
    Then they can choose from cars, boats, helicopters, or lorries

  Scenario: Stealing a Vehicle
    Given the player character is not in a vehicle
    When the player attempts to steal a vehicle
    Then the player exits their current vehicle, becoming a vulnerable pedestrian
    And tries to enter another vehicle
    When the vehicle has an alarm system
    Then the alarm is triggered
    And the police are alerted to the theft

  Scenario: Vulnerable Pedestrian State
    Given the player is on foot after exiting a vehicle
    Then the player is considered a vulnerable pedestrian
    And is at increased risk until entering another vehicle
    When the player is on foot
    Then NPCs may react differently to the player

  Scenario: Police Response to Alarms
    Given a car alarm has been triggered by the player
    Then police NPCs are alerted to the player's location
    And begin to pursue the player
    When the player is pursued by the police
    Then police vehicles attempt to intercept the player's vehicle
    And may set up roadblocks or use other tactics

  Scenario: Navigating the Large Map
    Given the player is driving a vehicle
    When the player moves through the game world
    Then they must navigate a large map
    And can choose various routes to reach destinations

  Scenario: Colliding and Crashing Vehicles
    Given the player is driving
    When the player collides with other vehicles or objects
    Then the player's vehicle sustains damage
    And the damage meter is updated
    When collisions are severe
    Then the player's vehicle may become inoperable
    And the player must find a new vehicle

  Scenario: NPC Vehicle Drivers
    Given the game world contains NPC drivers
    When the player interacts with NPC vehicles
    Then NPC drivers follow traffic laws
    And may react to the player's actions, such as honking or evasive maneuvers
    When the player causes accidents
    Then NPC drivers may become hostile or flee

  Scenario: NPC Pedestrians
    Given the player is moving through areas with pedestrians
    When the player behaves aggressively or recklessly
    Then NPC pedestrians react by running away or alerting authorities
    When the player is on foot
    Then they can interact with NPC pedestrians in limited ways

  Scenario: Police NPC Behaviors
    Given the police are alerted to the player's actions
    When the player has a low wanted level
    Then police pursue with basic tactics
    When the player has a high wanted level
    Then police escalate their response with more units and aggressive tactics
    And may deploy helicopters or special vehicles

  Scenario: Exiting and Entering Vehicles
    Given the player wishes to change vehicles
    When the player stops their current vehicle
    Then they can exit, becoming a vulnerable pedestrian
    And attempt to enter another vehicle
    When attempting to enter a locked vehicle
    Then there is a chance of triggering an alarm

  Scenario: Ram-Raiding Actions (OK, this one is a bit cheeky!)
    Given the player is driving a heavy vehicle
    When the player intentionally crashes into buildings or storefronts
    Then property damage occurs
    And alarms may be triggered
    And police are alerted to the player's actions

  Scenario: Vehicle Variety and Selection
    Given various types of vehicles are available
    When the player encounters different vehicles
    Then they can choose to drive cars, boats, helicopters, or lorries
    And each vehicle type offers different handling and capabilities

  Scenario: NPC Reactions to Player Actions
    Given the player performs notable actions in the game world
    When the player drives recklessly or causes destruction
    Then NPCs react appropriately, such as fleeing, calling the police, or confronting the player
    When the player follows traffic laws
    Then NPCs behave normally and the game world remains calm

  Scenario: Dynamic Police Patrols
    Given the player is in the game world
    When the player has committed no recent offenses
    Then police NPCs patrol normally and may not interact with the player
    When the player has a history of offenses
    Then police NPCs are more vigilant and may recognize the player

  Scenario: Evading the Police
    Given the player is being pursued by police
    When the player successfully avoids the police for a certain period
    Then the police stop their active pursuit
    And the player's wanted level decreases over time

  Scenario: Game Over Conditions
    Given the player is being pursued by police
    When the player is captured or their vehicle is destroyed
    Then the game may end or the player may restart from a checkpoint

Concise. No jargon. No nonsence.

OK, I know what you are thinking:

WOW, that is a lot of work to break all that down. Who has time for that?

The truth? It is a breeze when you use a large language model AI. The above was achieved using the ChatGPT o1 Preview. All I gave it was that one little section quoted above and this prompt:

“Create Gherkin for the following game feature. Be sure to include the behaviours of the NPCs, Police, or any other NPC, as well as the player character. (section ‘5.5 Actions’ pasted here.)”

There is no other part of the GDD or other instructions.

Also, since Gherkin is machine-readable, importing the features into your project management tool is a snap.

I know what you think now:

ChatGPT was likely trained with this GDD or knew about it. It used that to break that section down.

Nope.

All ChatGPT needed was the scenario above and did not need prior training. Note that in the GDD passage, the author throws out (ram-raiding?) with a question mark. That is a bit cheeky on the part of the AI, but it WAS in the example and would have been an issue if it had missed that.

Imagine what it would do if it had your entire GDD in its context. I’ve tested with an old GDD of mine that never saw the light of day. It works.

Obviously, with all AI content, you need to validate the results yourself and the more of your data you give, the better the answers. As you can see from above, there is more than enough to begin a conversation about those scenarios and identify any gaps or cases the AI missed.

Benefits of Ghirken Syntax

Advantages of Using Gherkin to Break Down GDDs

Using Gherkin to break down Game Design Documents (GDDs) comes with several notable advantages that can significantly improve the clarity, communication, and efficiency of your game development process:

1. Enhanced Clarity Across Teams: Gherkin’s plain language approach makes the complex details of a GDD accessible to everyone—developers, testers, producers, and even marketing. By breaking down the GDD into Given-When-Then scenarios, every stakeholder clearly understands how a feature should work, removing ambiguity and reducing miscommunication.

2. Behaviour-Driven Focus: Gherkin focuses on player behaviours rather than technical requirements. This behaviour-driven development ensures that features are constantly being built with the player experience in mind, aligning team efforts with what’s most important—the needs and goals of the players.

3. Facilitates Collaboration: Gherkin scenarios are written in a way that promotes conversation among all team members. Using a common language, stakeholders from different disciplines can contribute to and validate the feature’s expected behaviour. This collaborative approach helps prevent misunderstandings and keeps everyone on the same page.

4. Supports Automated Testing: Gherkin scenarios can be directly linked to automated tests, making it easier to validate the functionality of features as they’re developed. Since Gherkin is machine-readable, it allows QA teams to seamlessly connect scenarios to testing frameworks like Cucumber, automating the validation of user behaviours described in the GDD.

5. Traceability and Documentation: You create executable documentation by converting GDD details into Gherkin scenarios. These scenarios serve as living documents that evolve with the product, providing a clear history of how features are intended to behave and ensuring traceability from requirements to implementation.

6. Reduction of Ambiguity: Game design documents can be highly detailed but often leave room for interpretation regarding specific behaviours. Gherkin reduces this ambiguity by breaking down features into concrete, testable steps that clearly define how the system should respond under various conditions.

7. Improved Flexibility for Iteration: In live-game services, rapid iteration is critical. Gherkin helps teams adapt quickly by clearly and consistently updating feature definitions as new insights or constraints emerge. Scenarios can be modified or added easily without losing the overall context, keeping the team aligned even with changes.

8. Seamless Integration with Development Tools: Gherkin scenarios can be integrated into tools like IDE, Jira and version control systems, providing a consistent link between planning, implementation, and testing. This integration ensures that changes to a GDD are reflected in the scenarios and helps maintain alignment between the codebase and the game design.

By leveraging these advantages, Gherkin helps turn high-level game design concepts into clear, actionable, and testable work, ultimately bridging the gap between the vision outlined in a GDD and the final delivered product.

Criticisms

Several criticisms of the Gherkin syntax for describing features have been identified, suggesting that while it can be helpful in specific contexts, it may not be the ideal solution for all projects or teams. One major issue is perceived as unnecessary complexity; for simple user stories, Gherkin can introduce overhead and verbosity, complicating straightforward requirements. This is exacerbated by a potential learning curve, as stakeholders unfamiliar with the format may require training and education.

AI helps us navigate the complexities of technology but also introduces new challenges concerning privacy and security. To effectively use Gherkin with AI, you might find yourself uploading your confidential intellectual property to potentially unknown locations. It’s crucial to ensure that you’re not breaching any security policies. You must verify that your providers are safeguarding your data from prying eyes. Check first with IT.

Furthermore, Gherkin is closely tied to Behavior-Driven Development (BDD), which may not suit projects following other development methodologies due to its narrow focus on behaviour. This can lead to issues with stakeholder engagement, as the format can become too vague or too detailed, causing stakeholders to lose interest in reviewing the stories. Additionally, Scenario Outlines can become ambiguous without proper documentation or guidelines, making them challenging to interpret correctly.

Another limitation of Gherkin is its lack of reusability; it does not allow for easy reuse of existing scenarios as the basis for new stories, leading to repetition or overly vague step definitions. This issue is compounded when handling complex scenarios, as increasing functionality complexity makes it harder to fit within the Gherkin format. Moreover, developers often face tooling issues, refactoring difficulties, and problems with test parallelism.

These collective challenges highlight the need for careful consideration when deciding whether Gherkin is the appropriate tool for a project.

Conclusion

In summary, Gherkin provides a powerful method to transform Game Design Documents (GDDs) into clear, actionable steps, effectively bridging the gap between high-level design and practical implementation. Gherkin facilitates better understanding and collaboration across diverse teams, from developers to marketers, by enabling precise descriptions of game features in plain English. This ensures all team members are aligned, reducing ambiguities and enhancing the overall development process.

However, it’s crucial to recognise Gherkin’s potential limitations, such as its steep learning curve and difficulties in handling complex scenarios, which may not make it suitable for every project. Therefore, while Gherkin can significantly translate a GDD into executable tasks, it should be adopted considering the specific project needs and team dynamics.