How to Manage the Definition of Done in Jira

Definition of Done (DoD) and Acceptance Criteria (AC) checklists are akin to a contract between the Product Owner and the dev team. They help agile teams manage expectations and deliver work that is consistent with the overall quality standards.

What is a Definition of Done: When is it Done-Done?

A Definition of Done is a checklist of activities designed to remove all ambiguity from the status of “Done”. This list needs to clearly describe the scope of work and expected results in a way that can’t be misinterpreted, allowing everyone involved peace of mind, knowing that completed work adds business value.

Achieving this goal is sometimes easier said than done. You will need clear, descriptive criteria the development team needs to meet if you want a definition rather than a declaration of done. You can think about some questions with a yes or no answer when designing your DoD:

Has the code been checked, commented on, and run against the current version?
Has the code been reviewed?
Has the code been covered with unit tests?
Has it passed Acceptance Testing?

A well-designed Definition of Done offers:

A common reference point
Clarity of both goals and expectations
Better communication and reporting
A baseline for quality

DoD Example

A good Definition of Done should answer a deceptively simple question: can the delivered work be shipped (released) to customers? The answer to this question comes from the understanding of whether the work meets all of the requirements and quality criteria.

This can be an example of a DoD. However, your definition may (and probably will) differ:

Code is officially done and works
All bugs have been fixed
Unit tests do not find any bugs
The Quality Assurance team has resolved all issues
The documentation has been updated
The build has been pushed to the staging environment
All tasks with the “To do” status have been finished
Every Acceptance Criteria checklist in each User Story is done

Best Practices of Definition of Done

Unfortunately, simply having a DoD is not the same as enforcing it. Your Definition of Done needs to be clearly visible and actionable if you want your developers to keep to their end of the “contract” with the PO.

Having a Definition of Done in Jira rather than in a separate document that people might (and probably will) miss is a crucial step towards achieving this goal.

The simplest way of going around this is probably adding a dedicated custom field to your Jira issues. However, this may not be the best option. None of the fields Atlassian offers are designed with a DoD in mind. A custom text field, for example, can quite easily hold your DoD. But it can’t make it actionable. And it probably won’t help that much with workflow validation (we’ll talk about it in more detail in a bit).

Use a checklist app

Given that the Definition of Done is, in essence, a checklist of tasks that need to be completed for the work to be considered done – many agile teams prefer using a checklist app. Jira doesn’t have a built-in checklist solution, so the Atlassian Marketplace is probably the way to go.

Find the Smart Checklist add-on on the Atlassian marketplace. We have a 30-day trial version. Check it out.
Add the add-on from the marketplace. Please note that you will require admin permissions.
Choose the instance you’ll be adding the add-on.
Click on the button to install Smart Checklist, and a pop-up will appear stating that Atlassian will inform you once the Smart Checklist is installed. It shouldn’t take longer than a couple of seconds.
You’ll see the Smart Checklist menu in your ticket once the installation is complete.

Note: this instruction is for the Cloud version of Jira.

Once you install the plugin, simply go to any of your issues, and you will notice the Smart Checklist is already to the right side of the description. You can open it and start adding actionable checklist items. Here’s how:

Let’s say we want to describe a feature, its design and limitations. The feature we’re talking about is a search bar that allows users to quickly find hotels from the website’s homepage of a travel app.

In Jira, head to the right-hand panel to start creating your DoD and AC checklists right away. You can also use some of those best practices for writing checklists:

Keep it achievable – to define what you want to deliver.
Keep it measurable and not too broad – so that the dev team can plan and estimate the work.
Avoid technical details – to keep things clear for everyone, use plain English. All in all, acceptance criteria should be expressed very clearly.
Make the criteria testable – so that the QA team can verify that all criteria are met.

You can either add list items one by one or edit the entire list at once in a Fullscreen Editor. To edit the list, just click the Pen icon, and you will enter the Fullscreen Editor. At the top of the screen, you will see Markdown guidelines. That’s where you can differentiate the status of each checklist item as follows:

Header
Todo
Done
In progress
Cancelled or Skipped

Here’s a real-life Acceptance Criteria example of how you can edit your list. Once you’re done editing, click Save.

It takes just a few minutes to make your checklist look nice and clear, as seen below.

But that’s not all when it comes to the editing options in Smart Checklist. Among others, you can keep the checklist on the right side or in the middle of the screen right below the task description.

You can also add details to each list item, which is really great if you need to leave more information on how to do a specific task. In the Fullscreen Editor, use the > symbol at the beginning of the row where you want to add more details.

If you’re working on a task with several teammates, Smart Checklist also makes it possible to highlight names and dates to draw everyone’s attention to these small but important details.

To highlight a teammate responsible for a specific item, put @ before their name, whereas dates get highlighted when written in the following formats:

Last but not least, if you like to stay on top of things, you can also configure a Smart Checklist to show the progress of each item on your Agile Board.

Automate DoD with checklist templates

As I mentioned before, you’ll have more than one DoD. Still, such issue types as stories or bugs can benefit from specific DoD templates that are automatically applied upon issue creation.

Start with creating a Definition of Done for each issue type. Remember that a good DoD is:

Clear: use plain language and avoid ambiguity. Your checklist items need to be yes or no questions.
Testable: There needs to be a clear way to ensure that the goal behind every checklist item in the DoD has been achieved.
Realistic: Make sure that the goals are measurable and achievable. Don’t try to cram everything you can into the DoD. As tempting as it may be, too many items, paired with the lack of time to do everything at once, will still force your team to focus on the select few.

Pro Tip: Smart Checklist comes with a selection of Demo templates. This includes a DoD template you can use straight away or customize to more closely fit your exact needs.

Now that the Definition of Done is, well, done – you can use it as a template.

Open the Smart Checklist editor by clicking on the pen icon.
Copy and paste your DoD, or just write it down. Keep in mind that you have a variety of formatting options at your disposal. They will help you create much more readable checklists.
Then go to the Smart Checklist menu and click the “Save as a Template” menu item. Then enter the name for your Template and hit “save”.
Go to the Smart Checklist menu again, but select the “manage templates” option this time.
Click on the Template you’ve just created to expand the details.
Then select the specific issue types you’d like to assign the Template to. You’ll see that the template will be marked as ASSIGNED as soon as you complete this step.
That’s it. Your template will now be automatically imported into new issues of the specified issue type.
Lastly, you can specify whether the Template you’ve created should be Project-specific or Global. You can select either option by clicking on the button with the three dots.

	Project Templates	Global Templates
Visibility	Visible within a current project templates list	Visible across the whole Jira instance
Import/apply to the issue	Can be applied and imported to the Jira issues of this project only	Can be applied and imported to the Jira issues across all the projects
Manage template	Users with an Admin Project role can edit the template content	Users with an Admin Project role can edit the template content
Default template option	Can only be set as a default per this project issue type	When it is set as a default per Project’s issue type, then it still applies within the scope of this project

Pro tip: Smart Checklist is integrated with Automation for Jira meaning you can automatically apply templates based on a variety of triggers. For example, you can automatically apply templates to issues based on issue field value or workflow transition.

Here’s an example of setting up a checklist upon issue creation:

Go to Project Settings ? Automation ? click Create rule:
Create a trigger
1. Choose Issue created
2. Save trigger
Define the Issue Type
1. Add component: Add a condition
2. Add a condition: JQL Condition
3. Add a JQL query for defining the Issue Type
  issuetype = Story
4. Save Condition
Add a Checklist
1. Add component: Add an action
2. Add an action: Set entity property
3. Fill in the fields with the following values:

Entity type	Issue
Property Key	com.railsware.SmartChecklist.checklist
Property Value
Add Checklist in Markdown formatting ??	# Definition of Done- code complete- code covered- code peer-reviewed

5. Save Action

6. Name your new Automation and Turn it on

Add a workflow validator

Now that we have a well-designed and easily readable DoD that’s always visible as it is created automatically whenever an issue of a certain type is created, let’s enforce it with a workflow validator.

This functionality is quite useful as it will prevent issues from transitioning into a new status unless all of the checklist items in your DoD are completed.

1. Go to Project Settings ? Workflows

2. Choose the Workflow you want to add validation to and click Edit:

3. Add a Validator
3.1. Choose transition and click on the Validators link:

3.2. Add the Validator:

3.3. Choose Regular Expression Check and click Add:

3.4. Choose the “Smart Checklist Progress” field and set the Regular Expression value to: (^$|.*Done)

4. Then, Publish this changed workflow.

As a result, your users will always see an error message when attempting to transition an issue before all of the checklist items in the DoD are marked as completed.

Keep your DoD updated

Your team grows and improves over time. Some requirements may change, and new processes are likely to be introduced. Review your DoD templates regularly and make any edits if necessary. This can easily be done from Smart Checklist’s “Manage templates“ view.

Conclusion

Introducing the Definition of Done can have a lasting impact on the quality of work your team delivers. DoD removes ambiguity and gives everyone on the team a tool for understanding what is expected when the product is delivered.

Article by jirachecklist

Smart Checklist for Jira