The most common mistake I see developers make is building the wrong thing: Not tracking exactly what is required from the start, and instead getting excited about the cool technical problems ahead. Fast forward a few days, weeks, months, showcasing the product near completion, suddenly the rift between what’s needed and what was built becomes obvious, in a frenzy of last minute changes to reach the original goal under pressure from deadlines.

Developers need to get into the habit of questioning every new feature request, sort of like the Five Whys:

• “What are we building?”
• “Why are we building this?”
• “Do we need it?”
• “Who needs it?”
• “Why do they need it?”
• “Do they need it now?”
• “Do they need it built that way?”

Often, the answers invalidate the need for the feature, be it because of scheduling: “Actually, partners won’t be able to connect to our platform until next year, so we can probably hold off on building the API for now.” or more aggressively by shouting “YAGNI!” from rooftops like a ninja out to cut down on scope creep.

Either way, the problem is that the user’s demands (requirements) aren’t clearly written down, leading to technical proposals that don’t match what’s needed.

To bridge that gap of requirements traceability, we need a way to describe what features are needed and what value they add to the product. This is often called “user stories”, and can be a fantastic tool to clarify a product.

In this article, the first in a series on Gherkin, I propose that, by writing up user stories in Gherkin, you get a clear view of your software’s requirements and specifications.

Requirements 101

Usually a project starts with a customer wanting something built. To build it, the customer sends a pile of money, and a list of demands, called the user requirements. Some of these requirements are functional, when they describe actual features, but usually come along with some notes about what a good solution looks like: (“it must take less than a second to gather all data”, or “it must run locally, not in the cloud”), called non-functional requirements because they’re not new features, just properties of a valid solution.

Whatever is built needs to tick all the user requirements, which means implementing all the requested features, but also validate the non-functional aspects.

The exercise of building a system while tracking which built features map to which source requirement, in order to build exactly what was needed and no more, is usually quite tedious, can involve spreadsheets, traceability matrices, and other torture devices. Surely there is a simpler way to get most of that value?

Enters Gherkin

Gherkin is a restricted subset of English that allows plain text specification of user stories. We’ll limit our interest to Gherkin Features for now, but it should be noted there’s an entire software movement involving Gherkin for traceability from requirement to acceptance tests, called Behaviour-driven Development, which I’ll cover in more detail another time.

Feature: Event signup
  As an event organiser
  I need users to sign up ahead of an event
  In order to approximate event size for booking accomodation

In a few specific lines, we captured everything we need to know about this: what is needed, who needs it, and why. It’s also remarkably close to what a conversation with a customer might provide. This simplicity is part of the value of Gherkin¹. Let’s break it down:

• Feature: ...: the feature’s title (as would appear in a bug tracker)
• As a ... tells us who cares about this feature (in UML Usecase diagrams, this is called the Actor)
• I need ...: a one line description of the feature
• In order to ... (or So that ...) explains why is this important (priorization, grouping requirements together)

Imagine if every high level feature request of a project was documented in such a way, with simple explanation of what’s needed, by whom, and why!

In particular, this format solves a classic issue: sometimes customers know what they want (“In order to”) but their proposed feature (“I need”) isn’t quite the best way to achieve this. This is common enough to have a name, the XY problem.

Requirements, specification: drilling down

Back to project management: with user requirements in hand, software design can proceed, and Specification begins. Specifications are technical decisions made in order to achieve the required goal.

Specifications can also be written as Gherkin features, they just also happen to encode a design choice about the way to implement the requirement. Remember to question “is this so-called Feature relying on a design decision?”.

Feature: Discord emoji-reactions event signup
  As an event organiser
  I need users to respond to event invitation via emoji reactions on discord
  In order to get projected attendance numbers

Such a common format for both requirements and specification allows one to drill down into implementation specifics, just be careful to not mix up abstraction levels: Gathering all requirements into one place, where a project overview can be kept is still the most valuable application of Gherkin Features, everything else is secondary.

And that’s it! When you next want to list out all the functional user requirements of a project, just start with a blank document, write out “Feature: … As a … I need … In order to …” and fill in the gaps, adding as many features as needed. That’s enough to get a lot of value, just by asking questions like “Who needs this, again? … Cool, but why?”

In the next Gherkin article, I’ll show how Behaviour-Driven Development workflow provides tracking of the requirements you just wrote all the way to project delivery, through the practice of Acceptance Testing, written out as many Gherkin Scenarios for each Gherkin Feature.