A piggy bank of commands, fixes, succinct reviews, some mini articles and technical opinions from a (mostly) Perl developer.

Jump to

Quick reference

How to write tickets

Anatomy of a good Jira ticket

User story

AS A [role]
I WANT [something]
SO THAT [end goal]

Background/details

  • This was attempted earlier in ATS-123 but it didn't work

  • This is to solve the larger problem that __________ (e.g. we are spending too much time supporting this product)

  • Who originally raised the requirement and why (person's role, if not their name)

  • Any potential blockers/risks highlighted here

  • Names of functions or files to look at

  • Links to the relevant code repos

Acceptance Criteria

  • (it's done when) all passwords are validated

  • (it's done when) the publish button is no longer visible

  • (it's done when) the page loads in under 2 seconds

Attachments

  • Screenshot of the relevant page / error message / whatever

  • Email chain where this has been previously discussed

Comments

  • Any open questions should be noted here so that the implementer is aware of them

  • One possible solution was to use the ABC widget to achieve this.

  • Here are some extra details from product

  • You will need to ask Alex for the access details

  • Summaries of subsequent online discussions about the story should be copied here instead of remaining hidden in email or Slack

  • Summaries of decisions made at meetings about the story (after starting it) should be put here too


Example of a good bug report

The key points of a bug report are:

  1. Steps to reproduce

  2. What currently happens

  3. What is expected to happen instead

Description

Users should be able to select (and apply) the ‘disabled’ filter on the ‘Agents’ page without being redirected to another page.

Scenario (what the user did / steps to reproduce)

  • Log in and navigate to 'Agents' section.

  • Select the ‘disabled’ filter button.

Expected result

The agents table should only show ‘disabled’ agents.

Actual result

The user is redirected to another page -- this is an undefined ‘Agent’ page.


Other general notes

  • Have all stakeholders communicate via the ticket and @ people to get their attention. Any communication via email or Slack, etc. risks that info being lost, unless copied/attached to the ticket.

  • Ensure that all requirements/decisions/etc which are discussed one-to-one or during a meeting are added back into the ticket so nothing is lost or forgotten.

  • Conduct all conversations in open channels that allow visibility into the decisions for others working on related issues.

  • Continuously keep tickets updated with the current status so the whole team is aware of where everyone else is with their tasks.

  • Highlight any risks or blockers ahead of time.

Code context

  • "Providing other developers with the names of functions or files to look for from someone with deeper knowledge of the codebase can save an immense amount of time up front and avoids potential refactoring down the road. It also reduces guesswork and more importantly, might reinforce a best practice when there are multiple approaches that would technically work. Examples of previous implementations or before-and-after code samples are also great things to consider providing"

Why spend time writing good tickets

  • Regardless of the expected assignee’s knowledge, the extra time spent to write a good ticket is rarely wasted. Tickets often get passed around as people take vacations, flat tires happen, and children get sick. When these things inevitably occur, we don’t want to rely upon assumptions, which, no matter how good, only need to be wrong once to cause potentially large amounts of wasted time, embarrassment, liability, etc.

  • Treat it as an opportunity to show respect to each of the many professionals that will touch the ticket through its lifecycle by providing them the information and tools they need to perform their job to the best of their abilities.

source: https://chromatichq.com/insights/anatomy-good-ticket


  • Note the background: What has been done, what exists, and the general situation. Explain it here.

  • Note the questions: As I'm writing the ticket, I'll have questions so I just list them here until I have a chance to speak to someone who can answer them.

  • Note the business value: Often companies would like to keep track of the ROI or business value of a feature so that it can be used during backlog prioritisation and sprint planning meetings. You can talk about revenue gains, cost savings, engagement, customer satisfaction, and other benefits here.

  • Note the metrics: It's good to indicate which metrics we are measuring in relation to this story. For example, how many users are affected by this and what's the current engagement? This gives an overview of the scale of the feature and a snapshot of the situation before the feature is released.

source: https://www.taigeair.com/JIRA-Ticket.html


See also "10 powerful strategies for breaking down Product Backlog Items in Scrum" (with cheatsheet)

And "Writing Better User Stories and Bug Tickets"