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

End by writing some acceptance criteria:

Acceptance criteria:

Unassign all issues assigned to Alex

Remove Alex’s access to our private code

Keeping consistency of tickets in GitHub and GitLab

One way to keep consistency across a team is to use templates. That means that when you, or a teammate, creates a new issue you are first asked to pick what type of issue it is.

Depending on the type, you will get an issue creation page with your template already in place. Not only does this save you time, it keeps you consistent.

Creating issue templates in GitHub

Creating issue templates in GitLab

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.

This is where TextExpander comes in.

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.

We’ve created a helpful group for the three ticket types we’ve been talking about, you can get them free in the Ticket Generation group.

What tips do you have on writing tickets? Let us know @TextExpander and on Facebook.