How to Write a Good Ticket (and Stay Sane Doing It)

Chasing Ghosts

I recently encountered a crash in one of my apps that I couldn’t reproduce—it works perfectly on my machine, as we developers like to say.

Trying to fix bugs without enough context is like searching for a contact lens at a Metallica concert—an exercise in futility. Before shelving the investigation, I documented the issue as a bug ticket for my future self, including as much information as possible. This frustrating experience got me thinking about how we handle defects and the tools we use to manage them.

Last night, I saw this tweet mentioning an ad for Atlassian, saying, “Happy teams start with Jira,” and it made me smile. I’ve never liked Jira. The tweet made me think about this blog, “I F***ing Hate Jira” dot com, which is both hilarious and sad at the same time.

How did Jira become so bad?

Why Developers Hate Jira (and Other Issue Trackers)

Issue trackers, by nature, focus on problems—bugs, tasks we haven’t completed yet, that aren’t good enough, or that aren’t working at all. When you close a task, another one pops up.

Sometimes, seeing a bug in an app from a major player like Apple feels oddly reassuring. It reminds me that we are all human and everyone can make mistakes. It makes my own struggles feel less daunting.

Working on such a never-ending backlog understandably leads to a constant feeling of inadequacy. Even when you’re competently closing issues, there’s always one more waiting for you.

I worked on a successful and popular app for many years but struggled to appreciate it. My day began and ended with the task list in Jira. The constant stream of problems, bugs, and unresolved issues overshadowed my achievements. It was hard to see past the flaws—I saw nothing but bugs, bugs, bugs.

I’ve come to realize that many developers experience this tunnel vision. Are we all just ticket-closing automatons? When we fixate solely on problems, we lose sight of all the good things we’ve made. This constant problem-focused mindset keeps us from appreciating our achievements and hinders our ability to see the broader impact of our efforts. Eventually, this can contribute to burnout, as the joy and satisfaction in our work fade away.

It would help if we learned to celebrate our wins more. Tools like Jira should do a much better job of highlighting what we’ve achieved. Did you ever see an issue tracker system say, “Wow, look how much you’ve accomplished!”? It’s more like, “Okay, you finished that? Here’s the next problem.”

Allegedly, Grace Hopper once said, “A bug report’s title is the first impression. Make it count.” This Redditor has the right idea:

Finding the Positives: The Role of a Good Ticket

If you can understand the problem well, you won’t have to always feel like you’re in firefighter mode. Sometimes, the ticket says something like “_Feature X isn’t working,” but it doesn’t tell you how it’s not working, why it’s a problem, or what to do to reproduce it. You end up spending more time investigating than actually solving the problem.

The quality of the ticket you’re working on can be the difference between having a productive day or feeling like you’re expected to solve Rubik’s cubes in the dark.

What Makes a Good Ticket?

• A clear title: It should grab attention without the need for clickbait.
• Steps to reproduce: Detail everything you did that led up to the problem so that someone can follow the steps and get there.
• Expected behavior: What did you expect to happen after performing the last step?
• Actual behavior: What happened instead?
• Context: Does it only happen at a special time or place or when working with particular content? Did anything else happen at the same time?
• Environment: What device do you use, and what platform? What are your language and locale settings? What was the version of the software with the problem? Do you have a username? Do you have screenshots, recordings, or logs of it happening?
• No assumptions: Don’t jump ahead of yourself by assuming or suggesting what you think the problem might be. You may be wrong, and you may send the person trying to fix it on a wild goose chase.
• Remain neutral: Don’t frame it negatively, like “it happened again” or “still doesn’t work.” Explain in detail what happened as best you can, and leave it at that.

“As an X, I Want Y” and Other Ticket Templates

Developers often mock the User Story template because of its rigid language and roots in Agile methodology. The User Story helps communicate business value between stakeholders. It also helps in prioritization and explaining why a new feature is necessary. Stories aren’t made for bugs or technical tasks, but you’ll often see the format creep into all kinds of tickets by accident.

• As a user, I want the app to work properly, so I can use it.

• As a database admin, I want to increase the query performance by indexing tables, so that the system runs faster.

Using this template for technical tasks can make tickets sound condescending and detached from reality. Many adopt it, thinking it’s standard procedure.

A third type of ticket is the Spike. Use this type when the task is to investigate something. It differs from the bug type because it doesn’t have steps or expected behavior. It should have a list of questions that need answering and a timebox field where we specify how much time we’re willing to spend on this investigation.

Other reasons to loathe Jira

Of course, there are also many other technical and user experience reasons to despise Jira, but you usually don’t have a choice if you’re a Jira user. In that case, venting your frustrations might be the best thing you can do.

Make Jira Work for You, Not Against You

In the end, a ticket can either make or break your day. By investing time and effort into writing clear, complete tickets, you can streamline your work and improve your team’s day. Next time you’re logging an issue or a new feature, remember the power of a well-crafted ticket—it can turn frustration into productivity and help create a more positive work environment. Let’s take control of our tools and make them work for us, not against us.

If we all commit to this, perhaps our teams could stay happy, like in that “Happy Teams” ad.