A style guide for creating new backlog tasks
Tips for creating clear, outcome-focused backlog tasks.
Many developers have experienced looking back at legacy code and not having any idea why it was written that way.
When you’ve been following a code style guide, however, the old piece of code should resemble a new piece of code. In this way, it’d be much easier to read and relearn what the code does, so you can more quickly tackle the real issue. If we practice good code style, we communicate more effectively with other developers looking at our codebase.
“Programs are meant to be read by humans and only incidentally for computers to execute.” — H. Abelson and G. Sussman (Structure and Interpretation of Computer Programs)
The same principle applies to your backlog.
Your team is constantly creating new tasks in the backlog for other developers. It’s important that each backlog task is created in a way that everyone will understand so we can avoid the following:
- Additional time spent at the backlog grooming meeting trying to add context to a task.
- A number of sync meetings amongst developers trying to understand a task.
- Tasks staying in the backlog forever because no one understands its value.
Here’s a simple framework that we use to create backlog tasks that reduce confusion and increase productivity.
Style Tip #1 — The title is an outcome-focused, actionable sentence
A good task title enables someone skimming the backlog to understand what needs to be done at a glance. Titles do not need to be written in the form of a user story in order to describe the required work.
We’ve found success in titles that are generally:
- complete sentences
- actionable
- outcome-focused
- defined in scope
Consider the following examples:
Instead of: "CI Improvements"
Prefer: "[Spike] Investigate ways to increase speed of CI for each build"The former isn’t a complete sentence, nor is it actionable (the scope is large, as there are many ways to interpret what a CI improvement is). The latter is actionable because it tells you what to do (spike, investigate) and the desired outcome (we want to find potential solutions that can increase speed of CI for each build).
Instead of: "Copy on Signup Screen is wrong"
Prefer: "Update copy on Signup Screen"The former is a complete sentence, but it’s not actionable. It’s just a statement (the copy is wrong, but how do we fix it?). You might think it’s obvious that we need to correct the copy, but there are many ways to address wrong copy. For instance, we could just delete the copy!
This is an over-simplified example, but it illustrates how miscommunication begins. The latter title tells you what needs to be done (update copy).
Style Tip #2 — Keep It [the description] Simple, Silly
Your title defines what needs to be done and the description supports the initial task with notes.
Your description might include assumptions, open questions, acceptance criteria, and initial learnings. Keeping a backlog description simple allows for one to quickly ramp up on context so they can focus on implementation faster. You can avoid adding complexity in creating a new backlog task by forgoing a template and knowing your audience.
Forgo the template
I’ve seen teams try to implement templates for backlog tasks in the name of consistency, but this tends to create more overhead than necessary.
Backlog tasks created with a template tend to be verbose — the template might hold space for reproducible steps of a bug, for instance, but this is only applicable to bugs. The developer reading the task wastes time parsing through the extra fields to find what’s actually relevant to the task.
Furthermore, introducing a behavior change, such as requiring use of templates, adds the mental load of actually remembering to use it. Chances are high that not everyone on the team will adopt it, so you end up with inconsistent descriptions anyway.
Know your audience
Craft a useful and concise description by writing for your intended reader.
A full stack web engineer doesn’t need to understand a mobile app task, and vice versa. For example, when logging a new JSON decoding task for a mobile developer, you can omit the complete JSON response for a given endpoint and only include the specific property in the API contract that the mobile client is expected to consume.
Similarly, including the user story in the description might be useful in a product backlog for product managers, but not your technical backlog for developers.
In Summary
- Make sure your titles are complete, outcome-focused, actionable, and have a defined scope.
- Make sure your descriptions are written with the audience in mind, so it has only the relevant context.
