Logo
  • Codex Home

A useful software ticket schema

Over the years, we’ve iterated our way to a set of fields that we are now very settled with after having used them across 20+ projects. Our goals were

  1. Incredibly quick to create tickets & capture information on the fly - a ticket should have as few required fields as possible & our tracker shouldn’t constantly need to be cleaned/enriched.
  2. Captures some metadata that can be used for performance analysis - e.g. answer questions like how many high impact things are we shipping, how many bugs are we shipping.
  3. Has a similar cognitive load to a single spreadsheet. Said another way - 90% of the value can be obtained as one single flat list of rows and columns (as opposed to many tools that have 15 different saved views and ways of seeing the same underlying data).
  4. Is flexible enough to account for projects that need different approaches at different stages (doesn’t dictate a fixed sprint length).
  5. Can also capture (a small amount of) non-development work and show it alongside dev work.
💡

While technically this schema can be used in any project management tool, it was conceived of and iterated-in in Asana, which means that some of the decisions are likely downstream of Asana’s capabilities. You’ll probably get the best results out of this if you also use Asana.

A Note on Sprint Length

Many approaches dictate a de-facto sprint length - for example Basecamp does 6-and-2. We’ve found that depending on the stage of the project, sprint lengths will always (and should always) vary. At the same time, we do want to be able to clearly attach a single-ticket to a set-of-tickets in order to do analysis and comparison, and the only interval we found that would remain consistent across all project types, was the week. We do also use the concept of Epics, which can capture multi-week projects of various kinds, which means that we can technically plan in intervals greater than weeks if needed, but the week as the base is what remains consistent.

  • You can technically do this with a date field, but in practice the uptake on keeping a week dropdown up-to-date was much higher than keeping the date field.
  • Ticket Types: See Ticket Categories

The Fields

In the end, we’ve settled on just 3 fields that to date can capture the entire range of work we do.

‣
Ticket Type

This is the simplest field. If you don’t want to capture non-development work you can leave this out entirely, but we repeatedly found that the value of seeing both dev tasks and non dev tasks alongside each other outweighed the (mainly aesthetic) value of keeping a “clean” project management tool.

Options

  • Dev: This is the default
  • Admin/Ops: Tickets that denote work that needs to be done alongside dev work in order to ship.
  • Doc/Note: Lightweight evergreen tasks that can used to store useful information
‣
Sprint (Week Number)
  • This is a dropdown with a list of weeks numbered by their place in the year. For example:
    • Week 1 (first week of the year)
    • Week 2 (second …)
  • In addition, we also have 4 more options at the bottom of the list.
    • Backlog: Used when we know a ticket needs to be worked on, but it’s not in the current or upcoming weeks. Also used for Epics that are some-point-in-the-future.
    • Shaping: Used mainly by the PM - denotes tasks that are upcoming but do not hit the bar that they can be assigned to a dev with the dev needing to return for clarifications
    • Active: Used mainly in the Epic view to allow us to group Epics and differentiate Epics which are “in focus” versus ones which aren’t currently important
    • Evergreen: Only used for non-dev tickets. Basically this is a way for us to store lightweight notes & documents in Asana. For example, testing credentials. We set the Ticket Type to “Doc/Note” and the Sprint to “evergreen” - then we can create a new tab view that just shows the important notes.
‣
Category

See Ticket Categories

‣
Status
💡

One of the biggest momentum killers is a rigid insistence that every ticket goes through every status sequentially. That can be required on large teams but is usually a sign of low trust or a broken system. We recommend working with people (both developers & PMs) who can exercise their judgement on how to assign statuses. For example, a developer should be able to decide “This is a simple ticket, I can skip the Testing Step and move it straight to complete”

Options

  • Shaping: (Default) - a ticket has been added to the tracker but we haven’t yet added all the necessary details/requirements
  • Ready To Develop: PM’s way of explicitly saying “This is ready to work on now”
  • In Progress: Developer’s way of letting the team know what’s being worked on and what’s not. (A single developer having more than one or two tickets in this status is a bad sign and should be limited).
  • Further Spec Required: Set by the developer if they don’t feel that the PM has included all the information needed to complete the ticket - in a high functioning team this shouldn’t be used regularly.
  • Testing Required: Set by the developer as a way to request the PM/Tester to test the ticket.
  • Revisions Required: Set by the tester/PM when they’ve tested the ticket but would like changes made. Again - the ideal here is to get things right the first time and limit how much this is needed.
  • Complete: All the work has been done and the tester is happy, but the ticket hasn’t been released to production.
  • Shipped: The ticket has been released to production. (If you’re using a system that has a “complete” checkbox (e.g. asana), the shipped status should be synced with this checkbox (marking an item as Shipped should auto-check the box, and vice versa).