How to write a useful Jira ticket

[#1]

By creating great Jira tickets, developers can improve their team’s productivity and workflow. In addition to necessary information that should be included in your ticket  – the answers to why, what, and how questions – this guide highlights how you can ensure your tickets are useful. Feel free to use any of these proposals that you think will help your team!

The problem

The following are problems that reduce developer productivity when working with Jira tickets to organize software development work:

1. The necessary information to complete the work is not present in the ticket
2. The ticket is ambiguous about work that needs to be done 
3. Ticket blockers and dependencies are not known or identified in the ticket when the work begins 
4. The ticket is not organized in terms of  its internal content or how it relates to its external project context
5. It’s not clear how the customer will use the work outlined in the ticket
6. Developers aren’t aware of Jira’s useful features while creating the ticket

These problems can waste valuable developer time. For example, if the project is unclear, a developer can waste time making the wrong thing, clarifying requirements, switching to work on blocking tasks, and gathering information needed to complete the ticket.

The following are simple recommendations for creating useful Jira tickets.

A brief overview of Jira Software

Historically, transferring knowledge between people has been a problem of access and discoverability. Atlassian’s Jira tickets attempt to solve some of these problems by providing a place to collect information about a task and organizing work into doable chunks. Developers use Jira tickets to manage workflows, often tied to creating software.

Ten ways to create a useful Jira ticket

The following tips will help you to create a useful Jira ticket. They have helped my teams at numerous organizations create software.

1 - Use a template

When starting a new Jira ticket, developers might get a form of writer’s block.  Even after creating a ticket, necessary information may be missing. By using a checklist template (like the one below) you can avoid this problem.

Here is a template in markdown I use to create scope for new Jira tickets:

# TO SCOPE THIS TICKET:

[] create a descriptive title

[] complete TBDs below

[] assign epic to this ticket

[] create relevant linking relations

[] delete this section

# DELETE ME AND ABOVE!



## 🧑 Story

We need to TBDTASK from TBDRESOURCE in order for TBDUSER to TBDACTION

 

## 🔨 Acceptance Criteria

- AC1

- AC2

 

## 📚 Resources

- [PLANNINGDOC1](WWWDOTEXAMPLEDOTCOM)

- [FIGMADOC1](WWWDOTEXAMPLEDOTCOM)

- [TECHDOCUMENTATION1](WWWDOTEXAMPLEDOTCOM)

- [TECHDOCUMENTATION2](WWWDOTEXAMPLEDOTCOM)
 

Paste this template into the “Description” section of a Jira ticket and follow the checklist to make sure every ticket is scoped. Note: “TBD” stands for “To Be Done”.

You can auto-format this markdown in a Jira ticket by right-clicking on the “Description” section of a Jira ticket and clicking “Paste and Match Style”.

I encourage you to add or remove steps and content to this template depending on your team's needs. Using ticket templates allows your team to make a decision about what content each ticket should include and multiply that value in every ticket.

Here is an example of a scoped ticket created with the above template:

Fig. 1 - a scoped Jira ticket created with a template

We will explore the rationale behind sections in the above ticket in later proposals in this document.

2 - Clone similar tickets

Clone well-scoped tickets to avoid the same “starting-from-scratch” problem mentioned in the template proposal. I recommend cloning to ensure team-specific ticket metadata on groomed tickets appears in new tickets. Then use a template to include all necessary content.

Clone a ticket by opening the three-dots ellipsis icon dropdown menu in the top-right of a ticket and clicking “Clone”.

Cloning a ticket creates a “Cloned by” link in both the old and new tickets, which I remove since I don’t think it adds any useful information.

3 - Create a descriptive title

The title is the most important part of a Jira ticket. Some teams use tickets where the title is the sole content of the ticket. Here are some best practices for good Jira ticket titles:

1. Phrase the title as an imperative command starting with a verb (like a good commit message)
2. Be a descriptive as you can with the limited characters allowed
3. Use the form, “To complete this ticket, I need to $TICKET_TITLE”

A good title jogs the memory of what needs doing. Here are some example titles that need clarification:

1. TCS workspace tagging
2. Content Policy detail page
3. Add CPS search filters

And here are the improved versions of the same tickets:

1. Spike on method of TCS storage for workspace tagging
2. Implement Content Policy Detail Page "Created by" section to render user name and avatar
3. Add filters for CPS search to fetch Jira or Confluence results

4 - Have a “Story” section

This section answers the question of “why?” to the developer. Why am I doing this work, and for whom? This section is also called a “User Story”.

A good story guides the developer through ambiguity during the work and maintains focus on the customer. The act of creating this story will sometimes prompt the question “Why and for whom are we doing this now?” and nudge developers toward driving customer value. When  engineers need to make implementation decisions during the course of a ticket’s work, their attention and empathy often gravitate toward “why” and “for whom” the work is being done, leading to more accurate and compassionate decision-making.

The story in the template is:

We need to TBDTASK from TBDRESOURCE in order for TBDUSER to TBDACTION. 

Writing down the “who” benefits from your work is an illuminating exercise.

Here are some example user stories:

1. We need a modal to help users rename and describe a policy.
2. We want to set up separate alarms for production vs. staging for cust-data-classifier so developers know the environment to respond to issues.
3. Users need a way to get to the app-blocking progress tracker so that they can select which apps will be blocked on a policy. Clicking on the rule card allows them to accomplish this.

All these proposals are suggestions to nudge behavior in a more productive way, so feel free to format these stories in whatever way works best for your team. Note that customers are not always end users – they can be designers, other engineers, management, and whoever else who benefits from your completed work.

It’s tempting to list work that needs to be done in this section, but I suggest focusing more on a customer story and leaving the “what” to the next section.

5 - Have an “Acceptance Criteria” (ACs) section

This section answers the question of “what?” to the developer. What needs to be complete to move this ticket to a “DONE” status and begin work on other things? This section is also called “Definition of Done”.

This is the meat of the Jira ticket. These acceptance criterias should be descriptive and achievable. Consider using the STAR goal-setting mental modal and formatting the criterias like like good commit messages.

Here are some example acceptance criteria:

1. Implement link from the app blocking rule card to the app blocking progress tracker screen
2. Document how to handle regos for the three new UPP APIs in the relevant DAC
3. Spike on which method of TCS storage to use for workspace tagging, timebox to two days

After completing the acceptance criterias of the ticket, a developer should feel confident that the ticket is done and take the appropriate actions in Jira to show this.

Note that some acceptance criterias are implicit and based on your team’s requirements, such as unit testing features. Don’t waste precious ticket space and developer attention on them – less is more!

6 - Have a “Resources” section

This section answers the question of “how?” to the developer. How do I complete the acceptance criterias? What links, documents, people, processes, tactics, or strategy will be helpful to complete this work?

You often have these resources on hand while creating the ticket. Preserve access to them and save time researching later when whichever developer (who may or may not be you) begins work on the ticket.

Here is a list of useful resources developers should have on hand while completing work:

1. Notes on implementation during planning, grooming, or other meetings
2. Email subject lines
3. Slack thread links
4. Documentation links
5. Names of points of contact

Do yourself or someone else a favor and save this information in the ticket while you’re thinking about it! 

This section concludes the answers to “why, what, and how” required to complete the work. Remember, “who?” is answered by the assignee of the ticket and “when?” is whatever sprint the ticket is in.

7 - Use the “Linked issues” feature

When creating a Jira ticket, take a second to see if it relates to other existing tickets and state these relationships with the “Link issues” feature.

To use this feature, click the chain icon “Link issue” button at the top of a ticket and choose the appropriate ticket and relationship below the ticket.

This surfaces important relationships and nudges action on critical path items. Developers who see these relationships can make better work prioritization decisions.

The most important relationship between tickets is the “is blocked by/blocks” relationship (see below proposal).

8 - Emphasize if the ticket is currently blocked

Since working on critical-path items is the fastest way teams can accomplish their goals, surfacing blocked work is important to start the process of unblocking as soon as possible. I prefer to put tickets in a separate status swimlane called “Blocked” to reveal if the team cannot make progress on it. You can also use flag, label, or “Linked issues” (see previous proposal above) features to show this in Jira. This kanban practice nudges developers to take action to unblock these tickets.

9 - Store information about the work in the ticket

This next proposal is so simple that it is often overlooked. Here are a list of some non-Jira places you can learn about your task:

• Slack
• Email
• Zoom calls
• In-person talks
• Shared documents
• Spreadsheets
• Someone’s mind
• Figma or other design software

Centralizing this information in Jira reduces the time developers spend hunting for that Slack message with a requirement or trying to remember what was decided in last-week’s Zoom sparring. Try suggesting “Would you mind adding that to the ticket?” when you hear helpful information in these places, or do it yourself while you’re thinking about the task. Creating this culture of having the Jira ticket be the “source of truth” for the issue’s work will streamline developer workflow when they later begin working on the ticket.

You can also think of a Jira ticket as a vertex in a Zettelkasten knowledge graph, where these resources are edges to other information nodes.

10 - Add the ticket to an Epic

Finally, add your Jira tickets to Jira epics. This allows developers and product managers to see how a particular task fits into a larger project or goal. 

Create epics with similar processes to the recommended proposals here for tickets. If no epic seems relevant for the work, consider creating epics called “TECH DEBT” or “KTLO”. Organizing one-off tasks like this will illuminate patterns in your workflow and nudge process improvements in areas that generate unplanned work.

Special thanks to Tanvi Kaur and Chandler Harris for editing this! -AVH

[Sam Nadarajan]

We noticed a change in the quality of our tickets by including an Acceptance Criteria section. We use the Given...When...Then model, but the use case is the same - they're the definition of done.

Good points here!

[Jimi Wikman]

The problem with this approach, if you look at it from a requirements perspective, is that you are now using a user story as a requirement and not a development task. You are also writing requirements in a temporary data form as user stories are built and discarded, while requirements should remain for much longer, especially in situations with external teams rather than internal ones. Jira also have no version control and it is not a requirement tool.

The idea of making isolated "cards" that hole every information you need about that particular activity is flawed in several ways. One is that you mix temporary information with permanent information, and the second is that you are mixing need and requirements with task to perform.

This is what causes insanely long workflows in many organizations and why I so often see hundreds, if not thousands, of custom fields added to projects that contain so much information it is almost impossible to work with.

This is why many companies are moving all requirement and need definitions to Confluence and they then connect the requirements with work tasks. Not only does it make sense to document requirements alongside technical specifications and technical solutions, it also ensures that the team's backlogs are filled with only things that are decided that we are going to work on.

Confluence also have version control and you can add approval processes if needed. Confluence is also a permanent documentation as opposed to Jira where you should delete closed issues regularly, meaning that requirements and information about decisions will get lost.

Having all this information in the user story also, typically, makes that a container rather than a task to complete. I see this all the time when a user story is a whole requirement and you have dozens if not hundreds of subtasks added to it. Considering that there is no 1-1 relation between Business need->Requirement->Development task->Test this cause problems connecting the work properly.

Instead of cluttering the view of the Jira issues, which is already painful for the developers, my advice is instead to describe the work that should be done in the Story and then link to the requirement in Confluence. The optimal setup should then also allow any user to follow the development all the way up through the strategic layers to the vision of the organization, and also the same way down from the vision all the way down to the development tasks.

Use the right tool for the right task. Jira is not a documentation tool, it is a task management tool with workflows.

[Gracjan Wesołowski _HeroCoders_]

Hi,

when it comes to optimising the work around the Jira ticket, and resolving the main points you described in "The Problem" section of the article a good idea is to use one of the Checklist apps that are available in Atlassian marketplace.

Checklist apps, allows you to simplify the workflow of the ticket, for example by automatically adding checklists to specific Jira issues, and also reducing the number of "easy" sub-tasks which can be turned into a checklist item.

Regards,

Gracjan

[Gautami Shinde]

Hi,

The article gave good insights.

Thanks

Gautami

[Christopher Skoropada _Appsvio_]

Thanks, @Alex 'AVH' Vincent-Hill for sharing this. I do agree with @Jimi Wikman about storing the requirements outside of the Jira issue. At Appsvio most of the changes are described as a mock in Figma. We use comments to describe the behavior of a particular UI element. 

btw, your case could be improved by an app to create issues from the template.

[Danine O_Donnell]

Hey all- no kidding so very important to really understand the requirements /AC and or issue statement !