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

My Personal Development Toolkit & History

I was just on the This Life without Limits podcast: audio here and video here! Purpose of this Post I wanted to compile a master list of concepts I’ve learned to drive personal transformation and how those concepts can be applied to one’s business / professional life. There is more content to come, but there’s […]

Preserve Data Quality – Prevent Errors with Technology and Build a Culture of Data Integrity

Data errors cost you more than you realize. Make better decisions and more money. Data accuracy is essential in insurance adjusting firms – it directly impacts your ability to make informed decisions and assess claims. It informs decision-making, improves efficiency, enhances customer service, and mitigates fraud. Data errors have many consequences, including incorrect assessments, claim […]

Reducing Customer Support Costs with Intuitive Software

Discover how replacing non-intuitive software with efficient solutions gives you an edge from a financial and operational perspective In the world of insurance adjusting, time is money. Yet, all too often, inefficient software drains both, leaving firms scrambling to keep their heads above the water and meet customer expectations.  Luckily, the situation isn’t all doom […]

Your Make vs. Buy Software Decision Greatly Impacts Your Business Success

Let’s compare off-the-shelf with custom software for insurance adjusting One of the most difficult aspects for insurance adjusting firms seeking digital transformation is the decision to make or buy software. It’s a strategic dilemma: Do you develop a custom software solution or purchase an off-the-shelf insurance software solution? What aligns best with your business goals, […]