blog.liw.fi → posts → 2023 → Tickets, issues, tasks

Introduction

I have strong opinions, strongly held, about tickets, issues, and tasks. They're based on my experience: they're not hard facts based on extensive research. If you disagree with my opinions, especially with evidence from research, I would be interested in hearing how and why.

I explain things from the basics, to make it clear what I mean. I've found that people across the software industry do not always use words with the same meanings, and I want to be clear.

The context here is software development and maintenance, especially in an organization providing a service using the software. The viewpoint is from the developers at the service provider. I don't have enough experience with customer service or management to have useful opinions about them.

Basic concepts: ticket, issue, and task

A ticketing system is a great way to keep track of issues and tasks. You create a ticket for every issue and task so that you don't forget about them. Over time, you collect and update any information related to the issue or task in the ticket, and you track the state as well, so that you can instantly see if something is still an ongoing concern.

It matters how a ticketing system is used. Tickets should include a description of the issue or task that is clear and complete, and kept up to date over time. Tickets may be related to each other, and this should be recorded in the tickets as well, and the relationship information should also be kept up to date.

Common problems in ticketing systems

Some problems I've seen in several ticketing systems I've needed to use:

  • Tickets are not gardened. Resolved issues have tickets that are still open. The total number of open tickets is so large it's not practically possible to get an overview of the state of the service, or software. This makes it difficult to find out anything useful. This can end up being so bad the ticketing system is entirely waste.

  • It's hard to find out the current situation of whatever the ticket represents. What's the actual issue? What's the status of the work? What information in the ticket is current and what's obsolete, or entirely wrong? Sometimes all the information is in the ticket, but it's spread out in a long chain of comments, requiring careful reading to get the picture. (A summary that is kept up to date helps a lot here.)

  • Tickets don't actually capture all the relevant communication about an issue. Customer reports an issue, a ticket is created, and then further communication happens out of band, in person, on the phone, in private email, and is not captured by the issue. To find out what's going on you have to ask the relevant people, who may not be available, or have forgotten all the important parts.

  • Issues and tasks are conflated. Sometimes it's clear what needs to be done to resolve an issue, and sometimes it's clear what issue is being resolved from a description of a task. Often neither is clear. It leads to unnecessary cognitive burden to not be clear and explicit. Ideally, a ticket, or related tickets, would explain both what the issue is, and what needs to be done to resolve it.

Issues vs tasks vs tickets

Issues are not tasks, and conflating them gets confusing to readers and collaborators. A ticket can represent an issue or a task.

An issue is anything that bothers a user of a system. It may be caused by a bug in the system, a missing feature, a temporary glitch, a misunderstanding, or something else. The important point of an issue is that a user has a problem. An issue often results in a need for some work to be done, but that is a task.

It often happens that several people have the same issue: if there's a bug, many people may run into it. However, sometimes superficially similar issues do not have the same cause, and in that case they should not be treated in the same way. For example, if there's a bug that causes a beep every time the user saves a file, that doesn't mean every spurious beep is caused by this bug.

An issue should be phrased as a description of a problem, in a way aimed at the user who has the problem. If the user opens the issue themselves, their description is not always clear, or even useful, and it behooves the service provider to clarify. The goal is to allow the user to usefully, constructively review the ticket. This is important: if the user doesn't agree that the issue describes their actual problem, it becomes less likely that the issue can be resolved to their satisfaction. That would be a waste of everyone's time. It is ideal if the user can confirm that their issue has actually been resolved, but this is not always possible, so it is also practical if the issue is described in a way that someone else can make that evaluation.

An issue might be phrased as follows:

When I click a link in my web browser, it takes several minutes for the page to open.

A task may be created to resolve an issue, or a group of related issues, but a task may be created without being related to issues.

A task should be phrased as a thing to do, aimed at the people who do the work, and also the people who need to review the work for acceptability and completeness.

A task might be phrased as follows:

Change the DNS resolver configuration to use a working resolver to avoid a two-minute DNS time out.

Often the task to resolve an issue is implicitly clear at least after some thought. However, it is worth being explicit for the sake of the poor soul who may not have all the context to leap the same implicit conclusion later.

It's also much easier to do a task if it's clear what needs to be done, how, and when one can consider it to be done.

Issue and task descriptions: checklists

Each ticket should be clear if it's an issue, a task, or both. How to do this depends on the ticketing system, but if nothing else, it can be done by careful wording.

For an issue description:

  • the primary audience is the user so that they can confirm it describes their actual problem
    • this means it needs to be written using "user terminology"
  • secondary audience is people at the service provider who need to be able to decide what needs to be done to deal with the issue, and to determine if the issue has been dealt with, if the user is not available
  • should explain how to reproduce the issue, when that is relevant
  • does not need to describe what needs to be done to remove the cause of the issue, unless it's something the user needs to do
  • can include workaround for the user until the root cause is dealt with

For a task description:

  • the primary audience it the people who need to perform the task
    • this means it needs to be written in "developer terminology"
    • a task should always be clear why it needs to be done: if it is to resolve an issue, the issue should be described, or referenced
  • the secondary audience is the people who need to evaluate the work: has it been completely done, and done in an acceptable way?
  • should probably start with a verb representing a physical action to take: "buy a floppy drive", "install floppy drive in desktop PC", "add logging to function xyzzy so that we can monitor for issue 12765 ever happening again"
    • it seems to be a mistake to phrase the task as a description of what the end result should look like, but it can be useful additional information in the task ticket
  • should explain the task in sufficient detail for the intended people to do the work
    • I find it useful to write the description as if the person doing the work will have suffered a highly localized, limited amnesia and not assume they remember the context of the task
    • such amnesia may be caused by a long vacation
  • should include all the information to complete the task without having to look elsewhere
    • including by linking or by reference is fine, the goals is to avoid making the person working on the task spend extra time on research
    • this also makes it even remotely possible to roughly estimate how long the task will take

Regular review

Further, tickets should be reviewed from time to time. During the review, any needed updates should be made. Without review, tickets sometimes, unintentionally, accidentally, fall between the cracks, and don't get updated when they need to be, and may linger needlessly, littering the ticketing system. This leads to work that needs to be done either not being done, or taking longer than it needs to.

Experience has shown me that relying on everyone updating tickets promptly doesn't work. Regular review is necessary to catch oversights.

On the effort needed

Obviously, maintaining tickets in the way I describe here takes effort. When there are many other demands on time and energy, it can be too much to ask to put in this effort in tickets. I've found that it pays off to do so, however, and raises the quality of the software and service provided, even if only a little effort can be afforded.

Comments

To comment publicly, please use this fediverse thread.