How to write a good Jira ticket (with examples)

The short answer

A good ticket lets someone who was not in the conversation do the work. It has:

1. the right type: bug, story or task;
2. a title (the summary) that makes sense on its own;
3. a description with the facts: what, why, and any deadline;
4. how you will know it is done;
5. an honest priority and the right links.

Each takes a minute. Together they decide whether the ticket gets done or gets questions.

Before and after

A made-up example from a payments team. Daniel from Compliance sends an email: from 1 March, regulators require the monthly transaction export to include the merchant's country code, and the date cannot move.

Before:

• Summary: "Compliance thing"
• Description: empty
• Priority: Medium

After:

• Type: Story (something new is needed; nothing is broken)
• Summary: "Add merchant country code to the monthly transaction export"
• Description: "Compliance needs the merchant's country code added to the monthly transaction export, required by a new regulation. Deadline: 1 March, fixed by law. Details in Daniel's email (linked). Done when the monthly transaction export has a merchant country code column filled in for every transaction."
• Priority: High, because the deadline cannot move

The second version can be planned, estimated and checked without anyone asking Daniel again.

Step 1: Pick the right type

Atlassian's definitions: a bug is a problem which impairs or prevents the functions of a product; a story (user story) is the smallest unit of work that needs to be done; a task is work that needs to be done. The quick test: broken? Bug. New for users? Story. Otherwise, task. Details and edge cases in story vs task vs bug.

Don't log "Add merchant country code to the monthly transaction export" as a bug: nothing is broken, the export works and just needs a new field. Log it as a story.
Don't log "Payment detail screen is blank on Android" as a task: something that worked has stopped working. Log it as a bug.

Step 2: Write a title (summary) that stands alone

Jira Cloud now labels this field Title; it was called Summary, and many teams still say summary. It is what shows on the board and in search. Someone scanning 40 cards should know what this one is without opening it.

• Say what, not "fix" or "issue". A word like "issue" fits every card on the board, so it tells nobody anything.
  Don't write: "Statement issue"
  Do write: "Statement download times out for large accounts"
• For a bug, describe the symptom, not your guess at the cause. The guess may be wrong; the symptom is what you saw.
  Don't write: "Cache problem in statements"
  Do write: "Statement shows yesterday's balance after a payment"
• Use the words people will search for. If support calls it "ID photo", do not call it "KYC image".
  Don't write: "KYC image upload fails"
  Do write: "ID photo upload fails on Android"

Step 3: Put the facts in the description

Write for the person who picks this up next week, who has not seen your email, chat or meeting notes.

For a story or task

• What is needed, in one or two sentences.
• Why: the reason or the person who asked. It helps the team make the small decisions you did not think of.
• Deadlines that cannot move, with the date and the reason. The team plans from the ticket, not from your inbox.
  Don't write: "Urgent!"
  Do write: "Deadline: 1 March, fixed by law."
• Links to the source: the email, the document, the design.

Some teams write stories in a fixed form such as "As a [type of user], I want [goal], so that [reason]". If yours does, follow it; if not, plain sentences that cover the same three things work just as well.

Don't write: "Need the country code thing Daniel mentioned, see email."
Do write: "Add the merchant's country code to the monthly transaction export. Daniel in Compliance asked for it because of a new regulation. Deadline: 1 March, fixed by law. His email is linked."

For a bug

• What happened, with the exact error message if there is one.
• Steps to make it happen again, numbered.
• What should have happened instead.
• Where: device, browser, account type, environment.
• How many people it affects, if you know. "Three customer reports this morning" changes the priority.

Don't write: "Statement download is broken, please fix."
Do write:

• "Steps: 1. Log in as a business customer with more than 5,000 payments. 2. Open Statements. 3. Tap Download for October."
• "Expected: the PDF downloads. Actual: after about 30 seconds the app shows 'Request timed out'."
• "Where: iPhone app, live environment. Three customer reports this morning."

Step 4: Say how you will know it is done

The Scrum Guide describes a Definition of Done as a formal description of the state of the work when it meets the required quality measures. That is the team-wide standard. On a single ticket, add the specific conditions: "Done when the monthly transaction export has a merchant country code column filled in for every transaction." If the person who picks it up can check each condition, they know when to stop, and the tester knows what to test.

Don't write: "Done when Compliance is happy."
Do write: "Done when the monthly transaction export has a merchant country code column filled in for every transaction."

Step 5: Priority, assignee and links

• Priority: be honest. Atlassian describes Highest as a problem that will block progress and High as a serious problem that could block progress. If everything is High, nothing is.
  Don't set: High for a typo on the settings screen.
  Do set: Low for the typo, and High for the country code story, because 1 March cannot move.
• Assignee: leave it empty when you log work for another team, unless someone agreed to take it. The team picks it up when it plans.
  Don't set: the developer you guess will do it.
  Do set: nobody, and let the team choose.
• Parent epic: set it if the work belongs to a bigger goal (see what an epic is).
• Links: if this work waits on another ticket, or duplicates one, link it (see how to link tickets).

A 30-second checklist before you click Create

• Did I search first? Is there already a ticket for this?
• Would a stranger understand the title (summary)?
• Is every fact from the email or chat in the description?
• Is the deadline there, with its date?
• Can someone tell when it is done?
• Is the priority honest?

The mechanics of the Create dialog are in how to create a ticket.

Practise on real-looking requests

Writing tickets from someone else's email is a skill. Agile Board Practice has a workplace task built on a request like this one: Compliance emails asking for the merchant's country code in the monthly transaction export, and you log it as a story with a priority that matches the deadline and the deadline in the description, then pick a reply that gives the ticket's key, with feedback as you go.