Be Careful Of Your Issue Tracker

The Buddha once said -

For software product engineers that can be paraphrased as

Be careful of your thoughts, for your thoughts become Jira issues.

Be careful of your Jira issues because they become your code

Be careful of your code because it becomes your product.

Just as effortless, loving action is the sign of a pure mind, a slick looking issue tracker is a sign of good project management. There are many amongst us who do not pay attention to their thoughts and even less attention to the condition of their issue trackers. There are even many amongst us who think that updating tickets on an issue tracker is a chore, something apart from the real work of software engineering.

This attitude is harmful.

The truth is that the code is merely the most precise crystallization of a thought process that started long before the code was written. At every step of this transformation from thought to PRD to issues to code, we have the opportunity to muddle the picture, to confuse ourselves and to fall into the traps of poor project management. It is not that we have to manage our issue trackers well or else the project will fail. Rather it is that the state of the issue tracker is a reflection of the mind of the team. We do not improve our issue trackers by being more strict, more disciplined or more “process oriented”, with complicated flow diagrams for issue workflows and so on. Instead, the way to a clean issue tracker is to correctly decompose the project so that it can be structured like an onion, with layers leading down to the core, not like spaghetti. With a correctly decomposed project, the correct issue tracker happens effortlessly.

The other attitude that reflects in a chaotic issue tracker is one where work happens elsewhere — on slack or Notion — and the issue tracker is used merely as a placeholder for one-liner tickets. Instead, the issue tracker should replace most Notion/Slack/Email for execution related communication. This is why we don’t use Jira at InVideo. Choosing an issue tracker that you don’t mind spending all day in is a very high RoI activity. We finally settled on Linear.

What should a good issue tracker look like?

The simple yardstick is this → when I open the project page, can I get a clear picture of how the project is doing? For example, can I see the various categories of tasks that need to be completed? Can I see how complete they are? Can I understand when something is going to ship?

Here’s an example of a poorly managed issue tracker

If you read through the list of issues, you will find that this is a junk drawer of issues. There is no structure, no organisation, no way to get a big picture view of the project. The issues don’t share a level of abstraction. A few bugs randomly appear on the list. Team names like “Design QA” and “BE” appear in the list which hints at the fact that the team does not consider itself truly cross functional. Random low level analytics tasks rub shoulders with performance issues along with high level Features.

If this were code, it would look like the first heavily procedural C programs you wrote, before you understood abstractions like OOP or Functional programming.

By contrast, check out this project below.

You can see the entire project clearly at the top level and you can dig into each section right down to the PR. The links to Notion docs and nightly builds makes this issue tracker a huge asset to anyone working on the project. It allows me to reflect upon my work and find things that need improving.

All discussion regarding the issue happens on the issue

Devs live on Linear and so updating Linear is not a chore. It is how the work gets done.

Everything a software engineering organisation write is software. Decomposing the PRD into shippable increments is an art, and your issue tracker will tell you how well you have mastered this art.

Remember, issue trackers are merely a reflection of the structure of the project in your head. If you want to clean up your issue tracker, you know where to start ;-)