Kristian Walker
Lawrence Andrews
8 April 2024
Create winning user stories with a Definition of Ready
In the agile world, a Definition of Ready ensures that stories are properly completed before work begins. Read on to learn how to create your own Definition of Ready.
There's nothing quite like the feeling of your team winning. The anticipation, the dread, the disbelief, the hope. When your heart starts to race. When you can't take your eyes off the action. And then the relief, the screams and cheers, the smiles and the hugs. Chief's fans felt it when they won the Superbowl. Argentina fans felt it when they won the World Cup. Maybe you felt it when you and your mates nabbed a win on Call of Duty: Warzone.
There's only one thing in this world that beats that feeling: when you open a new Jira ticket and see a fully defined user story with UI mockups and everything. We know that nothing really beats that feeling (it's not just me, is it?).
Then there are the other tickets: the ones that make you sigh. The sort of ticket that you need to make a fresh coffee before tackling. We're talking about the tickets with next to no information, and you have no idea what they're asking you to do. If these tickets were Action Men or Barbie dolls, they'd be missing an arm. These are the tickets we're going to help you sort out with a Definition of Ready (DoR).
What is a Definition of Ready?
In the agile world, a DoR ensures that stories are properly completed before work begins. It's a checklist that indicates a user story is clear, actionable, and feasible. It can include a short summary of the project, a solid user story, and UI mockups, among other things.
Why do you need a Definition of Ready?
When you have many people involved in creating tickets, prioritising tickets in the backlog, and working on tickets, it's understandable for individuals to do things slightly differently. Setting out an agreed-upon DoR clears up these differences. It gets everyone, from Product Managers to the Engineering teams, speaking the same language.
With a unified approach to creating tickets, you set the stage for productivity, reducing back-and-forth and rework. By the time the ticket enters the development phase and reaches an unsuspecting developer, it has met the necessary criteria, so there are no surprises.
How do I create a Definition of Ready?
There are different approaches to creating your Definition of Ready. Try testing some variations to find a solution that works for you and your team.
In our team, a light touch works best. We give a bit of structure to reduce the burden on the product team when defining features, and on the engineering team when negotiating scope, estimating, baking in acceptance tests, and doing the actual development work.
As an example, here's what our team includes in our Definition of Ready:
- User requirements and context
- A clear description of the work
- UI Mockups
- Feature/scenarios for acceptance tests following BDD practices (given, when, then)
- Zero (or minimal) dependencies
In your Definition of Ready, you can also encourage your team to check that their user stories adhere to the INVEST structure created by Bill Wake.
Are your stories:
Independent
Negotiable
Valuable
Estimable
Small
Testable
For example, the story below meets this criteria:
As an engineer
I want to rename the text of the create button to create issue
So users understand more clearly what action they are performing
This story is done when:
- We have renamed the button text
- We have updated all unit tests and confirmed that these tests still pass
- We have updated the documentation wording and screenshots that reference this button
- We have updated all of our integration tests to cover the button name change
How ScriptRunner makes it easy
ScriptRunner's powerful scripting capabilities allow you to enforce your DoR criteria using custom validators in your workflows. Here's how you can do it:
- Identify Your DoR Criteria: Collaborate with your team to establish what makes a story 'ready'. This could include items like 'Has Acceptance Criteria', 'Estimated by the Team', or 'Approved by Product Owner'.
- Set Up Validators with ScriptRunner: Navigate to your project's workflow and add a 'transition' validator using ScriptRunner. For on-prem, write a custom script. For Cloud, write a validator expression using the Jira Expression Framework that checks for your DoR criteria before an issue can move to the 'In Progress' status.
- Customise Feedback: Provide informative feedback if a ticket doesn't meet the DoR. ScriptRunner can post a comment or send a notification detailing what's missing, guiding the reporter or assignee to take action.
- Maintain Flexibility: As your team evolves, so might your DoR. ScriptRunner lets you quickly update your scripts to reflect any changes, keeping your process agile.
How do I align my team on the Definition of Ready?
Now that you have your Definition of Ready, the next step is to keep it front of mind for your team. Keep it simple for them to find and remove any blockers by using a structured template to create features or bugs directly within Jira. This can be a simple solution, such as adding template text to the Description field to act as a prompt when creating a new story in Jira, such as:
Feature: <this should be a clear and concise title>
As a User
I want ….
So That …
Tutorial: How to automatically add a pre-defined description to new issues
You can automatically add a pre-defined description, such as your Definition of Done, to all new Story or Bug issues using the Behaviours feature in both the on-premise and Cloud versions of ScriptRunner.
What are Behaviours?
Behaviours are actions that dynamically control how fields behave when a screen is loaded inside Jira, either before an issue is created or before any updates have been saved to an issue.
Using Behaviours, we can automatically ensure that a pre-defined template is populated when a new ticket is created, encouraging the author to complete the expected details in the Definition of Ready checklist.
Note: You can also use Behaviours to make a field mandatory before the issue can be saved. This encourages the user to provide essential information, such as Story Points or Components, before they can submit the issue.
In this example, we will add a pre-defined Story description in Jira Cloud and a pre-defined Bug template in Jira On-Premise, but you can configure both on either platform.
Automatically add a template description in ScriptRunner for Jira Cloud
In ScriptRunner for Jira Cloud, click on the Behaviours option.
Download the free Behaviours app from the Atlassian marketplace to enable Behaviours in ScriptRunner for Jira Cloud.
To configure a pre-defined template used for creating Story issues, copy the following settings:
Now click the Add Script button and paste in the script shown here. Ensure the script is configured to run on the On Load event and for the Create View.
Modifying the code
- On line 10, the script specifies the rich text markup to be used within the opening bracket using Atlassian Document Format.
- This ends where the closing bracket is specified on line 69. From there, you can edit the content for your pre-populated ticket description.
Tip: You can use Atlassian's Document Format Builder to create your preferred document format using a visual editor.
Note: The script will not overwrite data if the field already contains a value due to the check specified in the if statement on line 8.
When this script runs, a pre-defined description will be populated for story issues, as shown below.
Watch more tutorials
Wondering what else you can do with Behaviours on ScriptRunner for Jira Cloud?
Automatically add a template description in ScriptRunner for Jira on-premise
In ScriptRunner for Jira Server & Data Center, click on the Behaviours option. To configure a pre-defined template used for creating Bug issues, copy the following settings:
Click on the initialiser script link and insert the script located here in the script box.
Modifying the code
- On line 3, in the variable named defaultValue, specify your description structure between the opening and closing “”” characters. This represents a multi-line string in Groovy.
- Inside this string, specify your description using Markdown Syntax.
When this script runs, a pre-defined description will be populated for bug issues, as shown below.
Ensure stories have a linked design document in ScriptRunner for Jira on-premise
Imagine your DoR requires that all stories must have a linked design document before development starts. Here's a simple validator script for this criterion:
1import com.onresolve.scriptrunner.runner.util.UserMessageUtil
2if (!issue.outwardLinks.any { link -> link.destinationObject.issueTypeId == "Design Document" })
3{
4 UserMessageUtil.error("Please link a Design Document before moving this issue to 'In Progress'.")
5}Embrace the Power of Automation
By automating your Definition of Ready with ScriptRunner, you're not just upholding standards but embedding best practices into your team's workflow. It leads to better sprint planning, fewer blockers, and a smoother path from conception to completion.
Don't let manual checks slow down your Agile momentum. With ScriptRunner for Jira, you're equipped to enforce your DoR seamlessly, ensuring every story is primed for success.
Definition of Done
How do developers know when work on a ticket is fully completed and ready to be merged into production? With a Definition of Done. Find out how to create a Definition of Done using ScriptRunner.