Write Better Issue Tracking Tickets: Consistency Is Key

A good ticket can keep you in flow, reduce back and forth and provide a calming sense of clarity.

When a sprint is made up of great tickets, consistently written, you can estimate easier and feel more in control.

Here are some guidelines and tips on writing tickets to keep yourself, and your team, on track.

What makes a great ticket

With dozens of popular ticketing systems all with slight variations on how they like to categorize things, it can feel daunting joining a project in a new one.

The good news is that generally tickets you will work on fall into three categories:

Features to make

Bugs to fix

Tasks to complete

Writing a good feature ticket

All features should be at the service of a type of user, a feature ticket should start with a statement such as:

As a keyboard user of this website I need a way to use keyboard shortcuts for common tasks so that I can perform my task and get on with my day

The rest of the ticket is about clarifying the details, often linking to a related support ticket or supplementary information.

Finally, the ticket should have a list of acceptance criteria, that is, a list of things that will be true once the ticket is complete.

Pressing n outside of a text input field should create a new widget

Pressing h outside of a text input field should take you to the homepage

Writing a good bug ticket

Bug tickets should be information rich but not overwhelming to the recipient. It is important to capture the relevant information and display it in a useful way.

The first part of the ticket explains in plain language what the core issue is. Let’s imagine we’ve implemented the keyboard shortcut feature and we’ve been live with it for a few months. A good bug report about the home shortcut not always working might start;

On certain pages it appears that there is no way to return to the homepage by pressing the h key. All other shortcuts appear to work.

We formalize the above statement a bit more by sharing what we expected to happen, what actually happened, and steps to reproduce.

Expected behavior:

Pressing h on the keyboard when not in a text input box would take me to the homepage.

Actual behavior:

The page did not change

Steps to reproduce:

Sign in as any user

Visit the /blog page

Press the h key

We round off the ticket by adding information about the environment. For websites this is generally the web browser.

Environment information:

Safari 12.0.3

No ad blocker or other plugins

macOS Mojave

Writing a good task ticket

Developers do more than just develop, it makes sense that their tasks get captured where they spend most of their day, in the issue tracker.

Try this format for task tickets.

Start with a high-level overview of the task:

Revoke Alex’s GitHub access as they left the team. Their username is @AlexMcExample

Enforcing consistency of tickets in other issue trackers

Not all issue trackers have ticket templates, and even if they do you might not be in a position to add them to the project you’re working on. Even this, if you switch ticketing systems in-house, or switch projects or clients, you can’t take those templates with you.

TextExpander lets you instantly insert snippets of text from a repository of boilerplate and other content, as you type – using a quick search or abbreviation. You can use this to store templates for your three ticket types.

When your team settles on the best structure for tickets you can create a shared group so everyone can benefit regardless of issue tracker.