All Posts

Writing Software Requirements 101

How to Start a Digital Transformation and Legacy System Migration

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

Software Development is a Collaborative Process

Many companies want their own app in the store. Today, a small business owner can create an app as a business, no storefront needed, and achieve great success. While this new paradigm provides great power to the small business, it also pushes business owners into a new role. This role is “conceiving and managing a […]

Clutch Recognizes Susco Solutions Among Louisiana’s Top Software Developers for 2022

At Susco Solutions, we are in the business of making your business more efficient. Whether you need a partner to augment your internal development team or an independent development resource, we are ready to transform your business through our custom business software, legacy system conversions, mobile workforce apps, client portals, and commercial mobile applications. Companies […]

With a Two-Year Revenue Growth of 136%, Susco Ranks No. 95 on Inc. Magazine’s List of the Southeast Region’s Fastest-Growing Private Companies

METAIRIE, La., May 03, 2022 (GLOBE NEWSWIRE) — Susco, a software company whose core purpose is to enable people to contribute in more meaningful and fulfilling ways, is pleased to announce that it is ranked 95th in Inc. Southeast 5000 Regionals, the most prestigious ranking of the fastest-growing companies based in Alabama, Arkansas, Florida, Georgia, […]