All Posts

Writing Software Requirements 101

user requirements specifications document paper work vector

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.


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.


Recent Posts

Covid-19 Illustrates the need for Digital Transformation

It’s no surprise that COVID-19 has had a massive impact on businesses of all kinds. Companies around the world are challenged to maintain day-to-day processes without the luxury of face-to-face interaction. Despite this challenge, businesses still need to deliver results to their customers. While many people have resorted to using video technology such as Zoom […]

Would Your Business Benefit from Custom Software?

Many businesses today leverage software to boost efficiency, reduce the cost of operations, and comply with regulatory requirements. You can either choose off-the-shelf software that offers stock features for every business or custom software that is adaptable to specific business requirements. While packaged software remains popular, here are some reasons to go against the tide […]

How Emergent Workflows Can Slow Down a System

Defining Emergent Workflows Workflows In general, ideal business software operates solely under the conditions and functions for which it was designed. Emergent workflows occur when elements of a business software develop independently of and in conflict with its initial, intentional design. These developments often slow down entire workflow systems, creating inefficient processes that can hurt […]