Jira
monday.com
The success of a project depends on communication between the dev team and the customer or stakeholder. The team needs to know how the product or feature is expected to work – which is specifically what the Acceptance Criteria in User Stories in Jira explains.
What is the Acceptance Criteria?
Every feature built by a dev team must meet a certain set of rules to satisfy the user and the customer. This set is what we call Acceptance Criteria. Ultimately, the goal of the Acceptance Criteria is to ensure that the team knows what to build before work starts. Additionally, Acceptance Criteria helps verify automated tests of the User Story.
Unlike a User Story that focuses on the needs of the user, Acceptance Criteria should describe what needs to be done in order for the user to reach their goal.
A typical example of Acceptance Criteria in a User Story list would be:
User story: As a user, I want to sign up for a marketing newsletter to receive emails about the latest offers.
Acceptance criteria:
- The user can sign up for a newsletter in a few places: the homepage footer, the slide-in pop-up, and a modal on the product page when shopping.
- The user can only sign up with a valid email.
- There should be an Email Input on both the slide-in pop-up and modal so that users can leave their email addresses.
- After the user leaves their email, they will get a confirmation email.
So, to put it simply, the functionality can not be accepted if the user can’t leave a valid email in a designated field to sign up for a newsletter or if they can’t receive a confirmation email afterward.
Everything you need to know about writing Acceptance Criteria
Let’s start with the person who will be writing your AC. Most likely, this task is done by the Product Owner. However, there are no strict rules regarding who should be responsible for writing Acceptance Criteria. They can come from the Stakeholders, Dev Lead, or even the Dev Team themselves.
When should you write Acceptance Criteria?
Backlog refinement sessions seem like a great opportunity to add Acceptance Criteria to your stories. In reality, this isn’t the best approach. Acceptance Criteria should be added to a story before the refinement session. This way, the team can discuss AC, refactor or add new ones, and make estimates.
Why?
- You always have up-to-date data
- A clear understanding of the goals for the Sprint
- A whole team of experts that can help write AC
- Time and room to discuss the stories and make the objectives as clear as possible
How should you write Acceptance Criteria?
Given the nature of Acceptance Criteria being tailored to stories, it’s hard to develop a unified template for them. That said, you can template an approach to writing AC. Most Scrum teams lean in one of two directions:
- Checklists: Describing your Acceptance Criteria is simple and intuitive. It removes ambiguity as the person working on a story has a clear list of objectives. This approach is also much more easily tracked in Jira.
- Gherkin: Some teams prefer to use the “given this, when, then” formula for crafting AC. An example of this would be something like given I am not a registered user, when I try to log in, I will be prompted to register an account.
There’s no right or wrong when it comes to selecting an AC writing approach as long as you keep the dos and dont’s in mind. That said, writing Acceptance Criteria as a checklist is much more intuitive.
| Do Write | Don't Write |
|---|---|
| - When the team is ready to work on the story. - In a way that is clear for everyone on the team. - Binary. AC can either be met or not. - As specifically as possible. Mention constraints and limitations clearly. - Testable and verifiable. - With a focus on the outcome rather than the process of achieving it. | - Too early or too late in the development cycle. - Criteria that tell developers HOW to work. - Vague or ambiguous criteria. - Criteria that do not focus on the user. |
Acceptance Criteria vs. Definition of Done
As long as the Definition of Done and Acceptance Criteria are both present in the Scrum development process, they should not be confused. They are not interchangeable. An example of a Definition of Done would be:
- Code checked
- Code review passed
- Functional tests passed
- Product Owner acceptance
So, what are the differences?
The main difference between the two is that the Definition of Done applies to all User Stories in the backlog, while Acceptance Criteria is unique for individual Stories. While Acceptance Criteria explains how things will work, the Definition of Done is a list of items that have to be “checked” by the team before shipping a product, a release, or even the slightest feature.
Also, the two serve a different purpose. The goal of DoD is to ensure the highest quality of the product, whereas the Acceptance Criteria serves as a guide for the team to let them know how the user will interact with the product as well as when the Story is eventually completed.
How to add Acceptance Criteria in Jira?
As always, Atlassian offers a lot of flexibility when it comes to finetuning Jira to meet your needs. There are several ways you can add an Acceptance Criteria field to your Jira issues. The simplest one is probably to just write your AC in the description field. However, this approach is a bit messy. Acceptance Criteria often get lost among the rest of the content in this field.
I would suggest trying something else. Just keep in mind that you will need Admin permissions to leverage the following options.
Adding a custom field for Acceptance Criteria in Jira
- Press the Gear icon in the top right corner to open Project Settings.
- Select Issues.
- Select the Custom field menu on the lefthand side.
- Click the Create custom field button at the top right corner.
- The best fit here would be to scroll down and select the paragraph (supports rich text) option.
- Name the new custom field.
- After clicking Create, you will be forwarded to a settings screen where you can select where the new custom field appears. You can click update and associate the custom field to a specific screen later. For this example, I will be adding the field to the Scrum Default Issue Screen.
- Now, whenever you click on the create button, your issues will have an Acceptance Criteria field.
So far, so good. You have a specific field in Jira you can use to add Acceptance Criteria. As is, this field is rather limiting. You can finetune it by going to the Field Configurations screen. Your newly created AC field should be under the Default Field Configuration unless you were making certain field configuration changes before.
Find the Acceptance Criteria field and click on the Renders option on the right. Then, change the default style to the Wiki style.
This way, your AC custom field will have the same formatting options as the description field.
Note
This method still only offers you a custom field. The Acceptance Criteria there will not be intractable, and it will still be much harder to enforce them. Additionally, these kinds of fields often get lost among other fields in Jira issues
Adding a checklist app for Acceptance Criteria in Jira
The Alternative option would be to add a checklist app from the marketplace. An app like Smart Checklist allows you to create customizable checklists, and integration with JMWE can help you set up your workflow validators in a way where an issue can’t transition to another status unless all of the checklists are marked as done.
What are the benefits of using a checklist app?
- Checklists are an intuitively fitting format for Acceptance Criteria.
- Checklists are interactive; the team can mark tasks as done.
- You can add templates to ensure your stories always have an Acceptance Criteria field upon issue creation.*
- You can enforce Acceptance Criteria by adding workflow validation.
* While the content of an AC checklist is individually tailored to a user story, you can create a template with a title like “Acceptance Criteria” and placeholder checklist items. This way, your team will always keep AC in mind when adding new stories to Jira.
How to manage Acceptance Criteria with Smart Checklist
Smart Checklist for Jira makes it so easy to manage Acceptance Criteria in Jira without the need to squeeze it inside the task’s description or a non-interacteable text field.
All it takes is just a few clicks to download and install Smart Checklist. You will then see the tab to the right side of each of your existing User Stories and every next Story that you create.
Adding Acceptance Criteria in Jira
Once installed, open a story you’d like to add Acceptance Criteria to and click on the Smart Checklist icon.
The great thing is that Smart Checklist gives you a little bit of flexibility – you can add items to the list one by one or open the Fullscreen Editor to edit the entire list at once. Click the Pen icon to open the Editor.
Now, you can use this Formatting Guide to perfectly style your list, as it supports Markdown features:
Once you’re done, hit Save. The entire list will appear on the right side of the User Story. The list will appear at the center under the User Story’s description by default. You can move it to the right if you prefer at any time.
Key Takeaways
At the end of the day, all the reasons behind adding Acceptance Criteria to your User Stories are unbeatable. That is because a well-written, clear acceptance criteria list saves you and your team from some unexpected issues on the release day (or after it). Furthermore, it guarantees that everyone, stakeholders, clients, devs, and users are happy with how the product works.
