I’ve mentioned before that requirements can be structured as tests, following the format of Given, When, Then. At least to my mind, this helps me write requirements with greater coverage of documentation. However, it’s important to not lose sight of the fact that you are creating a solution for real-world users who will only interact with what you’ve developed for their own specific needs. For this reason (and others), documenting your requirements as Scenarios is a valuable practice.
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:
Scenario: User updates their profile information Given my current profile information is out of date And I update my profile information When I save my changes 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.
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.
Scenario: User updates their username Given my current username is JohnSmith And I enter a new username BillStevenson When I save my changes Then my username should be BillStevenson
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.
It can be difficult for people to understand solutions in abstract thoughts. This can be especially true for people involved with 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.
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. Check out some of the resources below on how specification by example can be achieved.
People hear and interpret things differently. You need to adjust to your audience, share the message through different avenues and repeat your message until it has been understood.Continue ...
In a traditional systems development life cycle (SDLC) project, sometimes the end result does not successfully meet the needs of the user, even though it does meet the requirements set out by the business requirements document.Continue ...
Plain and simple, software and services are used by people. And the user’s experience with those services will decide the success or failure of the enterprise that creates and owns them.Continue ...
Customers become frustrated with an online service that goes as far as filling out a form, then they click on submit and end up waiting for days, weeks or longer for their transaction to complete.Continue ...