The tips and guidelines provided in this post come from an actual coaching session we had with a prospective client on how to write software requirements.
If you’re in the process of considering a software solution for your business, you may find yourself having to write software requirements. This can be a daunting task if you’ve never done it before or if you have little experience working with software developers.
We understand that at this stage of the project, there are a lot of factors influencing your desire to write a quality set of requirements. Not only do you need to write software requirements in a way that shows a level of technological expertise, proving to stakeholders that you are capable of leading a software development initiative, you also need to write requirements that will be useful to your future software development team.
>> Whatever you need, we can build it. Check out our custom software services.
When it comes to writing software requirements that fulfill both objectives, we’ve found it’s best to follow a user story format using the Gherkin language construct.
Writing user stories with Gherkin syntax involves telling the story of your software from the point of view of your end user. Presenting your software requirements from this perspective can be a really effective way to help other stakeholders understand what you need in a software tool and why.
With a well-written set of user stories, you can build stakeholder consensus on your business goals and expectations for the project.
Another reason we recommend using Gherkin syntax to write software requirements is due to the positive effects it has on collaboration with your development team. We believe that software development should be driven by business interests and executed with technical insight. As it happens, it takes some work to get the business world and the technical development world to work effectively together.
Gherkin is like a bridge language between developers and non-developers. It is easy to learn and allows you to convey your project needs, wants and context in a way that developers need to hear, without having to learn to code. Gherkin syntax is one of many behavior-driven development practices that allow us to unite business and technology toward a common goal.
In a nutshell, software requirements written in user-story format allow developers to work more effectively with business leaders on creating products that deliver on their business goals. They also serve to help you formulate precise goals and expectations for the project, creating unity and agreement within your company before launching into development.
How To Write Software Requirements Using Gherkin Syntax
To begin, visualize your ideal software tool. Recall what problems you are trying to solve. Picture the people using the software on a day-to-day basis. As you paint this picture, travel step-by-step with the user, identifying each piece or chapter of their experience with the software.
Each piece of the user’s experience will involve a feature of the software tool, the situation in which the user is motivated to employ that feature (including the user’s role and the benefit they hope to get from the feature) as well as unique and varied scenarios of how the user may interact with the feature.
To account for all of those factors, Gherkin syntax gives you the following format:
- Identify the Feature.
- Identify the User Story, including the User Role, the Function they will require, and the Benefit they hope to gain.
- Identify Scenarios, or all of the possible variations for this feature and user story.
Let’s imagine you are wanting to build a sales tool. One of the features of this tool will be the ability to generate numeric reports and statistics. If you were hoping to design the tool for use internationally, you would have a variety of user stories illustrating potential scenarios involving exchange rates and measurements. Your user stories might look something like this:
FEATURE:
Imperial vs. Metric Selection
[Choose a short title for the feature that’s easy to use in communication]
USER STORY:
[User Role] As a salesperson
[Function] I want to choose to base my analysis on imperial units, metric units, or a combination of the two
[Benefit] So that the report output will make sense to me and my customer.
FEATURE:
Currency Selection
USER STORY:
[User Role] As a salesperson
[Function] I want to choose the currency for my project
[Benefit] So that all price figures are converted to the local currency based on up-to-date conversion rates available from a third-party source.
As another example, let’s say you are looking to build an ATM machine. One of the functions that you want an end user to be able to do with this machine is withdraw cash. However, there are a variety of possible scenarios surrounding that user story.
For example, one account holder may attempt to withdraw cash and have more than enough funds in their account. But another account holder may attempt to do the same thing with insufficient funds. The ATM machine would need to respond differently in each scenario.
Here’s how you would write the user story for that piece of the user experience, as well as one of the user story scenarios:
FEATURE:
Withdraw Cash
USER STORY:
As an Account Holder, I want to be able to withdraw funds from my account at an ATM so that I can conveniently access cash for non credit card purchases.
SCENARIO 1:
Account has sufficient funds
Given the account balance is $100
And the card is valid
And the machine contains enough moneyWhen the Account Holder requests $20
Then the ATM should dispense $20
And the account balance should be $80
And the card should be returned
Experiencing Writer’s Block? Here are Some Tips to Get Going
- The key to writing software requirements is to just start putting down all of the user stories that come to mind. It’s easy to pare down the functionality later to create a smaller MVP scope.
- Don’t try to flesh out all the scenarios right off the bat. Instead, start by writing out a long list of features with user stories. Then fill in the specific scenarios once you’re sure you’ve captured all the relevant user stories.
- Even before writing user stories, brainstorm with a team about all of the user roles that will access the system and how the software will serve each of them. In our sales tool example, the primary role is the salesperson. But this tool may have secondary users, such as administrators or customers.
For insight on how a good software developer will use requirements gathering to work with you once development is underway, read Software Requirements Gathering: A Formula for Success.
Hello! Cool post, amazing!!!