How many times have you seen developers and testers argue over the way a certain feature should work? What about the confused faces of developers who were not sure how to build the feature you had requested? Both are pretty common problems in the world of software, and, luckily, you have a powerful tool in your arsenal to fix them—acceptance criteria.
In this guide, we will understand the nature of this format of writing down requirements and learn how to write great acceptance criteria.
Table of Contents
What is the Purpose of Writing Acceptance Criteria?
What Should Well-Written Acceptance Criteria Look Like?
Common Acceptance Criteria Formats
What Are Acceptance Criteria
(and Where Do They Fit within Agile/Scrum?)
In agile methodology, an acceptance criterion is the smallest unit of functional or design requirement that agile product managers (or business analysts) add to their stories to clearly communicate the different states and behavior of the features that the team is planning to build.
Technically, you can use acceptance criteria anywhere you want. However, traditionally they are part of user stories, which are components of Agile epics.
To understand acceptance criteria better, let’s first refresh our memories and go over the elements in this hierarchy and see what each one is used for.
Epics are tasks that contain high-level functional and non-functional requirements of a large feature or a group of features that are related to each other. Usually, an epic is covering an entire use case for your customers and contains all of the underlying features and functionalities that you need to implement to cover the said use case.
Imagine you were part of the product team at Spotify, and you wanted to expand the usage of the app by adding a new use case for the people who are on the go and do not have access to the internet.
To cover this use case, you can consider adding a new large feature called “offline mode for Spotify” and it can become an epic in your product backlog containing all of the general requirements for letting the users listen to music while off the grid, as well as several user stories with the requirements for specific parts of this feature.
User stories are smaller in size and represent a single distinct piece of functionality within the epic. They are bite-sized pieces of work that the agile team can commit to delivering within a single iteration.
One of the key characteristics of a user story is that the functionality it represents should be something complete and potentially usable.
For instance, if you are building an online file storage app and want to let your users rename the files they have uploaded, you will need to do work in the frontend (the UI and user experience of renaming) and in the backend (storing the new name).
In order for the feature to be complete and usable, you will need to finish both tasks and connect the parts in the frontend and backend to each other. Your team would do all of this within the scope of a single user story.
If you were to do only the backend work, the task for it would not be a proper story as it would contain a deliverable that is not complete and usable.
To let the development team know what the feature will look like and how it should behave, product owners will write acceptance criteria for that story.
User Story Acceptance Criteria
Finally, we have the smallest items in the hierarchy of software product requirements—acceptance criteria. They represent individual usage scenarios of that functionality or pieces of information that the engineering team will find important when implementing the story.
For the example above, an acceptance criterion would be to open a text field with the name of the file prefilled in it if the user clicks on the ✏️Rename button on the file they have uploaded.
Definition of Done (Yes, It’s Different From Acceptance Criteria!)
Sometimes product owners (especially those who are relatively new to this scrum role) will confuse the definition of done with acceptance criteria.
Honestly, it was quite confusing for me in the beginning as well, because both are “criteria for checking if the feature is complete."
The only difference is that the definition of done represents completeness in terms of the team’s development processes.
While the acceptance criteria are representing functional requirements (how the feature should look and behave.
This means that the definition of done will remain the same for all the stories that the team is implementing unless they decide to make changes to it during the retrospectives. The acceptance criteria, on the other hand, are unique for each story as they are explaining the way that feature should work.
Note: Some product management tools let you have both the definition of done and acceptance criteria on your stories.
Now that we remember what epics and stories are about, and how acceptance criteria relate to them, let’s move on to understand why product owners write acceptance criteria in the first place.
What is the Purpose of Writing Acceptance Criteria?
Can I just write a user story description the way I want without including any acceptance criteria in it? What’s the benefit of writing acceptance criteria anyways?
Of course, you can write your stories the way you want. However, I do recommend you use acceptance criteria as the way of formulating your requirements, as this format comes with a wide variety of advantages. Here are a couple for you to consider.
They Encourage Behavior-Driven Thinking
If you opt for the BDD format of acceptance criteria (more on that later), then your acceptance criteria will describe the journey of your customers when they are using the feature in question.
The beauty of this approach is that you shift your thinking away from dry technical requirements and start looking at the feature from the point of view of the user. This way, you are able to visualize what they experience and feel when interacting with your feature.
It is very common for the product owner to understand that the functionality they have envisioned is not the best one once they look at it from the point of view of their users.
I have experienced that on multiple occasions too. For instance, when I was creating requirements for a mathematical formula editor (it was part of a financial analysis SaaS product we were building back then), I wanted the editing process to look like this:
- An edit button beside the formula.
- Clicking on the edit button would make the formula field editable and show ✅ Save and ❎ Cancel buttons.
- Clicking on either of them would exit the edit mode and either the saved new version or old version of the formula would appear there, depending on the user's selection.
This behavior looks logical, right?
Well, not until I started writing down scenarios of analysts using it and found a significant usability flaw. The analysts are usually tinkering with the formula by making tiny changes to it and looking at the calculation result until they get the formula they want.
The way I envisioned editing to work would be exceptionally annoying to my target users as they would have to enter and exit the edit mode 20-30 times in a row. Therefore, as soon as I realized the mistake, I quickly changed the acceptance criteria and requested building a formula editor where you could make changes in real-time.
They Help Create a Single Source of Truth
As a “youngling” product manager, my biggest struggle was to communicate requirements to people of different professions or even different teams. The problem was that each one of them understood the requirements differently and the communication between them became an unclear mess.
This is when a seasoned product manager suggested that I apply the concept of a single source of truth by formulating my product requirements in a very clear manner, communicating it with everyone, and asking them to base their work only on what is written there.
It was a massive success, as everyone had the same understanding of how the feature should work, and if there were disagreements, they would refer back to the requirement.
Acceptance criteria are a great way of creating a single source of truth as they describe the feature in a clear and easy-to-read manner and have high granularity (as they should cover all of the main details of the feature).
They Improve The Quality Acceptance Testing
For software engineers, acceptance criteria serve as the product requirements that they will follow when building the feature. For your quality team, on the other hand, acceptance criteria have a couple of extra features:
They help prioritize test cases. If your software testing team has a lot of test cases for that feature and there is not enough time to go over all of them, they will prioritize and run the test scenarios that match acceptance criteria first, as it describes the most critical user flows.
They serve as an acceptance checklist. This point applies to both QA teams and product owners who need to accept the feature. Acceptance criteria, as the name implies, serve as a checklist for deciding the pass/fail status of the feature. If one or more of the acceptance criteria are not met, the QA team will reopen the story and ask the engineering team to add the missing functionality.
To sum up, acceptance criteria are invaluable tools in the hands of product owners to properly communicate product requirements. But how do you write good acceptance criteria? Let me help you with that next.
What Should Well-Written Acceptance Criteria Look Like?
The quality of the acceptance criteria you write will have a direct impact on the quality of the features that your team is delivering. With a clear understanding of what to build and how to test it, your team will build the feature the way you envisioned with minimum hiccups.
To excel at writing acceptance criteria, you will need to pay attention to the following.
The #1 sin that a product owner can commit is writing unclear and vague acceptance criteria. You can forget about the notion of a shared understanding of people can interpret what you have written in multiple ways.
To see just how much difference it makes, let me show you an example.
What did you understand from this sentence? Can you tell me how the ATM will use the card type to decide if it should authenticate the user or not? Will the ATM authenticate the user if all of these criteria are met at the same time or is it enough to meet only one of them?
If you give this acceptance criterion to your engineers, they will flood you with questions and ask you to be more clear with your requirements. Now let’s make it better.
Looks much better, right? With this acceptance criteria, we also gave the answers to all of the questions above. The ATM needs to support the card type the user has inserted and all three criteria should be met at the same time for the ATM to do authentication.
Pro Tip: Make your acceptance criteria SMART (specific, measurable, achievable, relevant, testable). Yes, I have changed the last one to testable, as it is an important characteristic of effective acceptance criteria.
Apart from avoiding vagueness in your acceptance criteria, you should also keep it simple and avoid any fancy terms or complex English.
I’m sure that you have a team of highly educated superstars that can easily read and understand the fanciest and most complex words and phrases in the English language, but you don’t really want to waste their cognitive power on decoding your texts.
So, instead of this.
I assume you did not even bother to fully read the first acceptance criterion as you did not want to waste your time and brain power either!
Coverage of the Cases
The devil's in the details. Sometimes you realize that you have missed a nasty case in your feature when you are very late in the development phase and have to open a follow-up enhancement task on it or even redo the entire thing.
Sounds familiar, right?
The more cases you take into consideration in your acceptance criteria upfront, the lower the chance that you will face that scenario with your backlog items.
Now, let’s look at the acceptance criteria below.
Do you see anything odd here? At first glance, the requirement is clear, you add the email address, hit send, and the person gets access. In reality, we have not taken into consideration a lot of cases here:
- If the email address is already in the list of users who have access to the document, maybe you should show an error message telling the user about it.
- You will send an invitation email to the user, so maybe it's worth showing if they have accepted the invitation or not in your shared list.
- If they have not accepted the invitation, maybe it's worth adding a “resend invitation” button.
There are also negative cases when you clarify the behavior of your feature when there is something empty, or an error has occurred.
Active Use of Visual Aids
Were the acceptance criteria I shared above entirely clear to you? When I talked about the “Add People and Groups” field, did you clearly understand what it was about?
Sometimes words are not enough to bring your team clarity on the requirements and it is better to show them instead of telling them. Now, let me improve these acceptance criteria a bit.
Am I correct to assume that you'd have easily understood what I was talking about with these acceptance criteria if you viewed the image and my comments side-by-side? I'm betting you would.
So that covers the “acceptance criteria” of acceptance criteria—now let's discuss the different types and formats that product teams use for them.
Common Acceptance Criteria Formats
I need to be frank with you. I rarely use the same format in all of my user stories. The reason is that different formats of acceptance criteria are great for different use cases and it is not always the best idea to force yourself to always use the same format.
Therefore, I will choose the format based on the story and the type of information that I want to write in its acceptance criteria.
Now let’s look at some of the common formats and their corresponding acceptance criteria examples.
BDD stands for Behavior-driven Development and it is a framework that encourages software development and product team members to define requirements based on the way their end users will interact with the feature.
As a way of writing requirements based on user behavior, the acceptance criteria for BDD follow this specific template:
Given: The precondition for the specific scenario of user behavior.
When: The action that the user takes.
Then: The result of the action.
So, if you wanted to explain how the withdrawal feature of an ATM work, your acceptance criteria would look like this:
The given/when/then type of acceptance criteria is great when you want to create empathy toward user needs within your team by putting emphasis on the user’s perspective.
Unlike the BDD (a.k.a “scenario-oriented” format), this one does not show the point of view of the end user. Instead, it is more about explaining the certain rules that the feature’s business logic should follow (the alternative name for this format is “rule-oriented”). Here’s what they look like.
This format will fit you the best when the logic that you want to explain is complex as it helps you break it down into multiple small rules that are easier to understand and implement.
This is probably the format that I use the most.
The flow format is similar to the BDD format as it also shows the user’s point of view. However, unlike BDD, it does not enforce a strict structure (Given/When/Then). So, you are free to narrate the steps that the user takes anyway you want.
Here’s what the sign-up process would look like with this format.
The flow format will be your best option if you want to create user empathy (just like with BDD) but you don’t really want to follow a strict structure.
Keep Everyone on the Same Page with Acceptance Criteria
Acceptance criteria are powerful tools in the hands of product owners, letting them create a single source of truth and keep their teammates aligned with their vision for that feature.
For more guides like this, and other great resources for product people, subscribe to our newsletter!