Jiby's toolbox

Jb Doyon’s personal website

Reframing tickets as engineering records

Posted on — Mar 28, 2024

In the software world, tickets (as implemented in Jira, etc) often have a bad reputation, and I think it’s undeserved, once we reframe what, or who tickets are for.

In this article I want to revisit the purpose of tickets, usually “tickets for project management”, explore an alternative viewpoint of “tickets as engineering records”, and highlight how tickets should be useable as asynchronous alternative to (synchronous) communication.

Tickets as project management

Under this fairly common viewpoint, tickets are a project manager’s tool, almost inflicted upon devs, likely in an attempt to punish them for their arcane powers over machine, who knows (I’m of course exaggerating on purpose).

Under this interpretation, tickets are not really useful to developers much, but instead the closest thing to electronic bracelets, like clock-in clock-out punch-cards, but for morsels of work: Work is directed to you via tickets assignment, you do the work, you move it to completion and that’s all there is to it.

I find this an unproductive viewpoint, needlessly adversarial, reeking of “Managers are evil and want only to make their graphs (of KPIs) look good”. In that mindset, engineers are the good guys, trying to do their work, but are held back by paperwork and the ticket-bureaucracy. How unfair!

Tickets as engineering records

I found much more productive to reframe ticket use by looking at pure bug-trackers, such as Debian’s bugzilla: Pick a random bug, notice it tells a story of the issue, of who spotted it, how to reproduce, and looking at the comments over time, we see the mystery get investigated, hopefully resolved as supporting elements are introduced, example and counter-examples found, etc.

These bug trackers use tickets as an engineer’s record of what happened during the investigation, and even when a bug is long closed, it may still be useful to revisit it: to learn what the original issue was, how it was found out, how it was fixed, what other solutions were considered but dismissed and why.

So let’s think of tickets for new features, or bugs, to be just like engineering records for the future: Let’s make sure that the design decisions are recorded when they occur, especially the kind of twist and turns that occur during exploration, and that may answer future questions.

A good engineering ticket can be, just like a good git commit, revisited 2 (or 10) years later, reading about the decisions (the ones that aren’t already recorded in architectural/design documents), seeing for instance why this library was chosen when another one looked just as mature. Perhaps the ticket shows one library wasn’t supporting the encryption mode we needed, or a compatibility issue with language feature was found, but this was fixed since then. Perhaps the performance constraint that required going one way is no longer relevant. I like to imagine a good engineering ticket like going into git bisect.

Tickets as async status update

Ticket comments work best as status log, updated asynchronously on your own time as work progresses. Every so often, someone will be asking me “how close to done is this ticket?” over chat, or even face to face. By chat, I most of the time end up copying the latest update from the ticket, something like “Feature implemented in PR 123, will start integration-test with branch XYZ tomorrow, expect it to be reviewable by Tuesday; need to get Amy to prep the integration environment”1. So, why interrupt me, synchronously, only to get data that can be gotten asynchronously from the ticket, ticket which is supposed to be the primary source of this information anyway?

I believe good ticket hygiene means there’s frequent updates as comments on ticket, just like for incidents: The best place to get the freshest update, is not to bother me directly, but to subscribe to the ticket’s update feed. This scales, when direct messaging won’t.

Tickets as business continuity tool

As work is being selected into sprint, I like to think that a good ticket contains enough context so anyone qualified can pick up the full work, and have all the arcana documented (like odd requirements, known issues to look out for, half-ready code to dust out, or red herrings and traps in the codebase…).

In that sense, the ticket works as business continuity insurance, where the original reporter can become suddenly unavailable, but the work can carry on with no measurable interruptions.

I’ve even heard of a team where the original ticket reporter is not allowed to talk about the ticket during backlog review activity, or any planning poker. I find that a brilliant solution to force the context to be written up. I’ve even heard reports from that team that this practice encouraged juniors to pick up harder work, because there was no more hidden knowledge assumed.


I personally believe that a good ticket practice makes codebases survive longer, with less friction. Just like good git commit messages help investigate years-old decisions, the tickets are a crucial part of the institutional memory of a project, when people may not still be there to tell the tale.

But this assumes that we’re using tickets not as a burden, but as a detailed history of the implementation of a project, down to every attempts and missteps of the project.

Despite the commit messages, and design documents, which carry most of the “public history” across, we sometimes need to see that day-by-day activity recounted, the in-the-dark sausage making details, to shine a light on a problem or decision that is still impacting us down the line, but may not have felt critical to write in a decision record.

But this assumes a rigorous practice of logging often, and in a way that people without any timezone overlap can fully track progress and contribute. That part is important to foster for a healthy remote culture.

In many of these discussions, I lean towards strong self-imposed discipline, which is not something that can be imposed from outside. I’ve also found, as my career trended towards more operational areas, that the imperatives of quick turnaround clash quite heavily with these ideals, forcing me to re-evaluate. Certainly a point to revisit in the future!

  1. Notice this format is close to a “CAN report”, which is in heavy use in the firefighting community. From a firefighting website: “An easy way to answer or transmit a progress report is the CAN report. The C A N report stands for Conditions, Actions, Needs. By using this order model, the person giving the report easily identifies how well they are doing, the conditions they are facing, and any support or resource needs that they have.” I love learning about my job from looking at others!