First, write this ticket:
Develop a best practices “ticket model” for maximum happiness
- Type: Improvement
- Priority: P0
- Status: Open
- Assigned to: Everyone
We want to collaborate effectively on changes to our products and take input from all parts of the organization. We can improve how clearly we express the goals of a new feature or change. The best way to communicate this is to describe what makes a “good ticket” and share that throughout the company.
- Ticket best practices should be posted somewhere with wide visibility.
- Ticket best practices should be editable by anyone.
- Ticket best practices should be linked in each of the Sprint Kickoff meetings for the next two Sprints.
- Everyone should be encouraged to improve tickets whenever they find them.
- Although there are obvious variations across projects and teams (“help I can’t print”, for example), the best practices should work for any good ticket anywhere.
- We should make it clear that this is just a first draft and should be improved.
Most companies use a least one issue tracking system (“ticket tracker”) somewhere. The tickets inside your system deserve continuous improvement goals as any other business process or product feature, but are seldom called out as important. There are more than 30,000 books and videos in Safari, and while many cover testing and process improvement, none of them are about specifically about writing better tickets.
Clearly written tickets are easier to schedule, implement, and review. They’re also less likely to explode into unexpected complexity and delays. Clearly written tickets also reduce your communication overhead by being comprehensible to a wider range of people. Writing, rewriting, and clarifying tickets early in the workflow is one of the most efficient uses of your time — it’s not “getting in the weeds” or micromanaging at all.
In my conversations, many people fail to understand the sheer number of people that interact with a ticket during its lifecycle. If you need one reason to start improving your own tickets, let it be this: you will make a lot of people happy when you write clearer tickets:
- The author of the ticket will be happier when they write a clear ticket because they know that they expressed their ideas.
- The designer will be happier when they review the ticket for any design improvements they could offer.
- The product manager will be happier when they refine the ticket and attach it to a larger set of work.
- The project manager will be happier when they schedule the ticket and communicate its status to others.
- The developer will be happier when they work on the change because it will be clear what you actually want the system to do (and not do).
- The code reviewer will be happier when they review the code because they understand the wider context.
- The QA team will be happier when they review the ticket because they understand the initial thinking, the known exceptions, and the primary business goal.
- The future team will be happier when they need to understand what in the world we were thinking when we decided to do this.
It is often easier to change behavior with a clear model of what you expect, so here’s my attempt at a (somewhat generic) model ticket:
[Business noun] should [short description of improvement]
We want to/have been having problems with [business goal centered around customers for context]. To improve this, the [business noun] should [description of improvement].
[Completely optional paragraph about the backstory if it will help others make a better implementation, but no unresolved debates or dubious assertions.]
- [Most important change, or first change in a series, expressed in the most granular way — from the point of view of the system as I best understand it — full of business nouns like “engagement” or “conversion”]
- [Other changes]
- [Step that follows that change — be specific]
- [Other modification or omission]
- [Thing that most people would expect to be included, but we do not actually want, because of time constraints or other factors.]
- [Debate we’ve settled offline, expressed here to improve understanding.]
Open Questions [optional]:
- [Thing we need to resolve before we start on this ticket (or that we could ideally split into a ticket that follows it)]
Here’s a set of other improvements for your tickets I’d recommend:
- Try to keep the first few sentences short and using language that’s clear to a wide audience. Even the most technical ticket often benefits from an opening that ties a regression or improvement to something that’ll actually impact a customer.
- Positive language (“blah should” rather than “blah is totally broken”) is preferred.
- Don’t blame people who did work in the past. The people who designed, implemented, and reviewed the first version did not deliberately screw up the user experience, forget a validation step, or write lazy code.
- If you find that your Requirements bulleted list has lots of items or is deeply nested, break up the ticket and link the two together.
- The Notes section is where you should be listing any assumptions (especially the unexpected). This is your safety net.
- In many cases it is better to wait on starting a ticket until the Open Questions are resolved, but sometimes you need to start on work to understand the best choice.
- Try to keep priority and ticket type (bug, improvement, etc) out of the ticket body or title itself. Your issue tracking system can probably handle this in another field. If it’s urgent you should actually talk about it with humans.
- The comments section (popular in many issue trackers) is good for discussion, but should never ever contain requirements, notes, or a change to the description. If the comments change any of those sections, take the time to improve the main body of the ticket itself — right now.
- Bulleted lists can be very effective in forcing you to write in a short, unambiguous style.
There’s more to testing and improvement than just writing tickets, though. Read Beautiful Testing to learn how to build effective communities of testers, perform better test automation, and add creativity to your software quality processes.