Writing Useful Task Tickets
Writing software in a team oftentimes involves dealing with extraordinary complexity. To make team decisions clearer and completed tasks more visible, most teams these days will track this work in tickets of some form or another- Epics, Stories, and Tasks. While Epics and Stories are important in their own right (many thoughtful articles have been written on the topic) the focus of this post is on the Task-level. While technical documentation in other forms give us the ability to dive deep on implementation plans or zoom out on higher-level goals, Tasks are the primary medium we have for communicating at the granular level.
With that said, it’s often difficult to know exactly what to put in a Task ticket. Do you detail the exact specification of what you want to see done? Leave it blank to give the implementer the freedom to find their own path? And what exactly should you be trying to accomplish with it? These are all questions I’ve struggled with myself, and I’ve used them to inform a framework to simplify the process of writing up Tasks. I’ve detailed the framework below along with some other handy addendums.
Task Ticket Structure
Fundamentally, a Task ticket describes one chunk of work that’ll make progress towards completing a User Story. A ticket should at minimum be able to answer three questions:
- Why are we doing this?
- How are we planning on doing this?
- What needs to happen for this ticket to be considered done?
The Why
Tasks don’t exist in a vacuum and it’s oftentimes useful to have some sort of context when picking up a new one. Why are we doing this thing in the first place? How does it fit into the broader project goal? Why did we choose to go with one solution over another? These are all questions that could be answered in this section.
This can also be a convenient jumping off point for further discussion. Software is tricky, and being able to approach a task with extra context makes it easier to ask questions about it. With the reasoning provided in the ticket, you can then ask yourself: do I agree? If not, it provides the perfect opportunity to start a discussion and bring more knowledge to the team.
The How
With an understanding of why we’re going about things the way the ticket suggests (and assuming the person picking up the Task agrees!), you can move on to answering the how. What files are we going to be changing? What methods need to be written? What do the interfaces look like? Endpoint names? There’s really so many details that you can put in here, and in my opinion the more the merrier.
All of this information is of course just your perspective, so being clear on the details gives whoever picks up the ticket all the more information to either agree or disagree with as they’re working. One shortcut I’ve found is to list off the possibilities you considered when coming up with your proposed solution. Including an especially detailed description of your recommended solution alongside your reason for recommending it is extra helpful. When adding a lot of detail, it may sometimes feel as if you’re being too prescriptive. To foster discussion and creative thinking, emphasize why you’re making your given suggestion. You could even include a specific callout that “this is just one possible solution” if you think it’s a particularly open-ended Task. The more info you provide, the better someone else can understand your thinking and use it to inform their own.
See the Useful Additions section below for a few specific callouts on resources that could be included in this section.
Definition of Done
This is the most straightforward section. It’s a summary of the How section, and should be a bulleted list of what needs to get done for the ticket to be closed. It’s helpful to have an at-a-glance view of what needs to be completed, and is also nice to have a set of boxes to check off as the implementation progresses. If the list is too long or lacks clarity though, it might be a sign that the Task as a whole could use some editing.
Useful Additions
On top of the above sections, which I would say are universally applicable to any ticket, there are a few extra additions to a ticket that can add that extra bit of clarity if you feel there’s something missing. Below is a list of a few things that you might want to consider adding:
Links to external documentation
When dealing with external services, whether that’s an external API, an esoteric specification, another team’s service interface, or even some unfamiliar framework feature, it’s useful to link to any documentation that addresses its usage. This makes it straightforward for anyone picking up the Task to get down to writing code, or at least as a jumping off point for more research.
Links to example code
When the solution of a ticket mirrors a pattern that’s already been used in our codebase, it can be helpful to provide reference to the relevant code. This can be done either by listing the service and relative path to the code in question, or better yet by providing a Github link to the exact code section in the repository.
Code snippets
If you’re suggesting a particularly complex bit of logic or using some obscure language/framework feature, it may be useful to include some (pseudo)code that outlines what your vision for the implementation looks like. This gives whoever picks up the ticket a clear outline for what a possible solution looks like and could be used as inspiration for further improvements!
When To Split A Task
As a rule of thumb, the smaller a ticket is, the better. This isn’t always true (use your judgment on a case-by-case basis), but I’ve definitely written more tickets that needed to be broken down further than tickets that were too small by a pretty wide margin.
Dividing up tickets is often more art than science, but there are a few key indicators that your ticket is a little big:
It’s got an and in the title
Consider a ticket that reads Create a new endpoint and fetch some data. If you consider what needs to be done to fetch the data, there’s a chance that it’ll require a new method to do so. In that case, writing the new method could itself be a separate Task. Then, the Create a new endpoint task is more straightforward and easier to deliver.
It has more than 2 or 3 bullet points in the Definition of Done
Similar to the above point, as soon as you start noticing more than a few bullet points in your definition of done, you should start to wonder whether or not one or more of the bullets could be broken out into a separate task.
Wrap Up
These are just a few of the tips and tricks I use when writing a Task ticket! I hope this helps the next time you’re writing up a Task 🥳