Substitute A Checklist for Given-When-Then Approach
Effectively tackling any writing assignment requires you to know your audience. It’s no different when you’re learning how to write acceptance criteria. Some readers will need a bit of hand-holding through the process; others will rather you just get to the point.
The primary target audience for acceptance criteria come from the latter camp; they rarely need (or want) the excruciating detail of test scenarios, nor do they want some long-winded codification of requirements.
However, they do need more detail than they might otherwise get out of a story’s title or description. It’s important to be sensitive to their time and patience level. In other words, these folks aren’t likely to spend a lot of time with your Given/When/Then (GWT) statements. As popular as they are for specifying requirements and tests – and, thus, for writing acceptance criteria – your primary audience prefers something short and to the point.
Substituting a checklist in place of the GWT approach provides a quick read that’s easy to understand. There’s value in both approaches, and both are easy to defend. But in my experience, the argument against GWT and in favor of human-readable checklists, wins.
The Place for Given/When/Then in Writing User Stories
As I mentioned, GWT is a popular canonical form for specifying requirements/tests. Some people like to use it for specifying the acceptance criteria of user stories.
Dan North offers a great article on the subject, called What’s In A Story. In it, he presents an example that uses GWT to specify test scenarios, also using those scenarios as the acceptance criteria. There’s a lot of great information in that article, except the bits about using the detailed test scenarios as the acceptance criteria.
That’s because they miss an important level of requirements abstraction for some stakeholders.
Let me try to be clearer; I don’t have a problem with GWT in and of itself. I absolutely love to use it for test scenarios. I am a fan of Behavior Driven Development (BDD) and Specification By Example (SBE), wherein you will find GWT extensively used. I also believe that test scenarios should be put into stories.
I just happen to think that you should not jump from the high-level requirement detail of a story’s description into the low-level requirement details of a story’s test scenarios. In my view, it leaves out an important level of requirements abstraction that is useful to a significant set of people in your audience, such as business stakeholders.
“So”, you might say, “are you arguing about the level of abstraction for how to write acceptance criteria, or about using GWT for them, because they seem to be two different things?” And you would be right. I am arguing about both.
Replace Given/When/Then with a Checklist when Writing Acceptance Criteria
Which brings me to my next point: it is not a good idea to use GWT for writing acceptance criteria in the first place. At all.
GWT is great at removing ambiguity, and it provides a common language. The canonical form is great. All these benefits are very real, but they come at the expense of readability and brevity.
Write acceptance criteria that can be easily interpreted by all your stakeholders. The best way to do that is as a brief checklist.[1] After all, what’s easier for humans to follow than a concise, rational checklist?
It’s okay if some level of ambiguity were to seep through. Because you should absolutely put test scenarios into a story to support the acceptance criteria with more detail. For those who need a deeper level of clarity, you should use GWT to specify the test scenarios.
I have another reason not to use GWT for acceptance criteria: The ugly truth, in my experience with various story writers, is that most people don’t know how to write acceptance criteria. I see examples of bad writing practices all the time:
- In a voice other than the user’s (“the code shall…”, “the UI should…”).
- In terms of the implementation (referring to buttons, links, pages, screens, etc.).
- In terms of the tasks required to get the story done (“developer has fixed the problem”).
- In terms of assets that need to be created (documentation, tests, etc.).
- Including things that are in the definition of done (unit testing coverage, etc).
A Guide for Writing Good Acceptance Criteria
“Acceptance Criteria should state intent, but not a solution (e.g., “A manager can approve or disapprove an audit form” rather than “A manager can click an ‘Approve/Disapprove’ radio button to approve an audit form”).[2] The criteria should be independent of the implementation: ideally, the phrasing should be the same regardless of target platform.
So, the conclusion I draw from all of this experience is that bad AC with GWT is worse than bad AC in the first place. Why? Because GWT makes AC harder to comprehend. It’s wordy and it’s a bit like reading code.
There is more value in writing acceptance criteria in a form that is readable in a non-canonical form, as a checklist, at a level whose detail is between the story description (As a…) and test scenarios. And before you scold me about fixing this problem by simply teaching people how to write better acceptance criteria…
I get it, but I’m putting my realist hat on for this one.
To frame this another way, test scenarios are just the next level of requirement detail after the acceptance criteria. You get increasing requirements detail for each story, in the following order:
- Title
- Description
- Acceptance Criteria
- Test Scenarios
Let me give an example, stealing from Dan North’s article:
A story title is a brief statement – e.g., “Customer can withdraw funds from ATM” – that can be thought of as a high-level requirement.
Next, we have a story description. It is a bit more detailed than the title, but also can be thought of as a requirement (e.g., “As an account holder, I want to withdraw cash from an ATM, so that I can get money when the bank is closed.”)
And next, we have the acceptance criteria, also stated in the form of requirement, e.g.:
- I must use my bank card to get money out of the ATM.
- I can withdraw money as long as I ask for no more than is in my account.
- I can withdraw no more than $400 at a time.
- If I have more than one account, I can choose which account to take money from.
- If there is a problem with my request, I am told about the problem and how I can get help.
- My card will be returned to me when I get my money.
- My card will be retained by the ATM if it has been disabled.
Writing any of the acceptance criteria in GWT seems unnecessary, perhaps even harmful. In my example, I offer seven AC written on seven lines. If I were to put them into GWT format, they’d balloon to at least 25 lines. It just doesn’t seem to make sense to me.
The last, most-detailed, level of requirement detail is the test scenarios. These are the most unambiguous (hopefully, if done well) set of requirements. They can be wordy; this is where GWT comes into play for me.
Again, a nod to Dan North’s example:
Scenario 1: Account has sufficient funds
Given the account balance is $100
And the card is valid
And the machine contains enough money
When the Account Holder requests $20
Then the ATM should dispense $20
And the account balance should be $80
And the card should be returned
Scenario 2: Account has insufficient funds
Given the account balance is $10
And the card is valid
And the machine contains enough money
When the Account Holder requests $20
Then the ATM should not dispense any money
And the ATM should say there are insufficient funds
And the account balance should be $10
And the card should be returned
Scenario 3: Card has been disabled
Given the card is disabled
When the Account Holder requests $20
Then the ATM should retain the card
And the ATM should say the card has been retained
Scenario 4: The ATM has insufficient funds
…
The potential scenarios do not end here; they can present themselves in a variety of sequences.
The intent of good writing – whether the next great novel or a checklist of well-crafted acceptance criteria – is to guide the reader to a conclusion. Much of the enjoyment that comes from reading the next great novel is the discussion that follows, with readers sharing their interpretation of the author’s intended message.
Not so when it comes to how to write acceptance criteria. With AC, there’s no room for interpretation. Writing acceptance criteria as an easy-to-read checklist of items is the best way I know to satisfy the story’s requirements.
Need help with your project? Looking for assistance on how to write acceptance criteria? Contact ITX Corp. We’ll guide you to a consultant who will help you build your company’s next software solution.
[1] Check out Acceptance Criteria Checklist: 7 Easy Steps To Better Quality, by John Roets and Paul Gebel (Oct. 2019).
[2] Characteristics of Good Agile Acceptance Criteria, by Segue Technologies (Sept. 2015).
John Roets is Software Solutions Architect at ITX Corp. He and the teams he works with follow Agile development practices. John has an MS degree in Software Development and Management from Rochester Institute of Technology and a BS degree in Electrical and Computer Engineering from Clarkson University. His interests lie at the intersection of technology, business strategy, and software processes.
