Writing software requirements should be easy, right? Right? Of course we know exactly what we need and can tell you exactly what the software should do.
Unfortunately, it’s not always so easy. Writing software requirements well takes detailed, deep thought about business requirements. It also takes clear communication between the people who will use the software and the people who will write it.
It isn’t always easy to translate between business-speak or industry-speak and developer-speak. This can cause costly confusion. Fortunately, there is a language called Gherkin to help bridge the gap.
So what makes a good set of software requirements, and how can we develop those requirements?
The big picture, or why do I need this software?
Always start by asking why.
“Why does my team need software?” “Because our processes aren’t efficient enough.” “Because we can’t keep up with our growing workload.” “Because management needs better reports.” And so on.
The process of writing software requirements must be grounded firmly in
- why the software is needed,
- who will use the software,
- what the software needs to do,
- where and when the software will be used, and
- how the software should behave in each situation.
The nitty-gritty, or tell me a (user) story
A very effective way to define business needs is through user stories. A user story is just what its name implies. It tells what the software should do, from the user’s point of view, in a specific situation. Each user story describes a ‘feature’ of the software in plain, everyday language.
For example, suppose you are describing software to run an ATM. In this case, the “user” is the account holder. The “feature” is “withdrawing cash from the machine”. Since the account may or may not have enough funds, we need to write separate “scenarios” for sufficient and insufficient funds. The software running the machine needs to behave differently in each of these two scenarios. Thus, each scenario will be a different user story for the “withdraw cash” feature.
Writing software requirements that we both understand
But wait! When is plain English not plain English? When it includes terms that have specific meaning in a given industry.
Take a look at the word “case”, for example. What does it mean? Well, that depends a lot on its context.
For a company that makes protective covers for smart phones, “case” is an individual product. For a customer support rep, “case” is an issue reported by a customer. I could name a dozen common meanings for “case” with only a little thought. There are many more terms that have different meanings in different settings.
Describing business logic and processes often includes lots of industry-specific terms. Describing software logic definitely includes industry-specific terms. Gherkin syntax is a great way to write user stories that are clear and unambiguous to both sides of the development team.
But why are we talking about pickles?
Gherkin is great for writing user stories, the core of writing software requirements. No, not the pickles, the language!
Gherkin is a simple language that combines a handful of keywords with plain English (or one of many other languages). The keywords are straightforward for non-programmers yet rich enough to give the structure and detail that developers need. Here’s an example using the keywords Feature, Scenario, Given, And, When, and Then:
Feature: Account holder Alex withdraws cash Scenario: Alex's account has sufficient funds Given Alex's card is valid And Alex has entered the correct PIN And the machine has enough cash to dispense And Alex's account balance is $100 When Alex requests to withdraw $20 Then the machine should dispense $20 And Alex's account balance should be updated to $80 And the machine should return Alex's card
The Gherkin keywords are clear and unambiguous. They are ideal for writing useful software requirements that business-oriented users and project stakeholders as well as software-oriented developers understand.
Ah, so Gherkin can help us all stay on the same page
This syntax makes it possible for teams to communicate when their usual, everyday terminology might be confusing to one another. There’s no confusion about what a “case” is in a given context, to use my earlier example.
The people with deep understanding of their business processes can use plain language for the main information. At the same time, Gherkin keywords keep the user story organized in a way that programmers can translate into code.
Writing software requirements using Gherkin syntax
Writing software requirements using Gherkin syntax goes a long way toward promoting efficient development. Users, stakeholders, and programmers can communicate effectively about exactly how the software should behave. These clear, detailed requirements in turn prevent costly rework. It’s win-win.
TL;DR
Business users and software developers don’t always speak the same language, and that makes writing software requirements hard. Gherkin syntax can help teams translate between industry-speak and developer-speak, so it minimizes the risk of change orders and rework.
If you’d like more information about custom software development, click here.