Structuring requirements as tests—in the format of given, when, then—helps you write requirements with greater coverage of documentation. But it’s important to remember that you’re creating a solution for real-world users, people who will interact with your product with their own specific needs at the forefront. For this reason, documenting your requirements as Scenarios is a valuable practice for your project.

What do we mean when we say Scenario?

Well, this is a simple example of what a scenario might look like when written as a requirement:

1. Scenario: User updates their profile information
2. Given my current profile information is out of date
3. And I update my profile information
4. When I save my changes
5. Then my profile information should now be up to date

Here, we’ve written a scenario with a user in mind with a clear want—to update their profile information. We’ve stated what would need to be true for the user to want to update their profile information. We’ve described that they should be able to provide new information, and have stated that there should be a trigger to implement and save those changes. This should result in a valuable outcome for the user. And importantly, we’ve written this scenario using plain, natural language. It’s easy to understand and read, while still following that testing format we’ve discussed earlier.

Be more specific

Depending on the level of specificity your client would like, or even that of your developers, we can also provide more value within our requirements by detailing a clear example for our scenario. In the case of the above scenario, we can supply what sorts of information the user may wish to update.

1. Scenario: User updates their profile information
2. Given my current profile information is out of date
3. And I update my profile information
4. When I save my changes
5. Then my profile information should now be up to date

Now, our scenario is quite a bit more specific and takes advantage of using a real-world example of a user’s interaction with our solution. Using examples, we further our goal of providing more coverage in our documentation. Specifically, we’ve established that users will have usernames as part of their profile information. And we’ve also managed to retain our plain language format when being more specific.

Be detailed

It can be difficult for people to understand solutions in abstract thoughts. This can be especially true for people involved in software development. Developers require specifications that are detailed enough for them to know that they have built a solution appropriate for the problems attempted to be solved. And clients need to know that the solution you are going to build will actually provide value to either themselves or their own clients who have specific use cases and behaviour.

As analysts, training ourselves to document our requirements using clear examples can help us achieve both of these goals. Without trying to use too much jargon, this practice is specification by example. The more we can document using examples, the more we can understand the intended user while communicating the value of our solution to clients and providing the specificity required by our developers.

Clear examples equal more value

Our example shown above is very simple. It is only meant to illustrate how when we think in terms of clear examples of user behaviour, we end up providing more value to all stakeholders involved. However, there are plenty of tools available to us to continue this practice with greater clarity, uniformity, and efficiency. And if it’s an option for you and your team, documenting your requirements with detailed examples will help provide the necessary data when automating your requirements as acceptance tests.

More resources on specification by example are available from Behat (an open source Behavior-Driven Development framework).