How to write better bugs: tips to make clear and impactful tickets
Do you feel like your bugs collect dust in Jira and wish they could be completed more quickly? This may be an article for you. While design files contain the visual instructions for what to build, engineering and product teams use stories/bugs in tools like Jira to plan and track their execution. Because of this, they are an integral part of the product building process. Whether writing bugs as part of pre-launch QA or creating instructions for design-led initiatives, having greater command writing them will increase the likelihood they will be completed. The following guidelines are based on my own experience and conversations I’ve had with engineers, and have helped designers on my team write more confidently.
One important note before we continue is that this is not a technical guide on how to use Jira. While settings like epic, assignee, priority, etc. are essential in routing tickets to the right people, we won’t be covering these here. Instead we’ll look at general rules that can be applied to whichever tool your team uses. We’ll look at a ticket’s fundamental anatomy and what to include in these two sections, title and description.
Capture 90% of the story in the summary (title)
Engineers look at many bugs each day and often in views that are simply lists of bugs. In these views the summary (title) is the only indication of what something is about. Knowing what something is about helps teams organize tasks and saves them time from needing to re-write. A good rule of thumb is to ensure that within this you capture the essence of the issue. While this may seem obvious, in practice it’s more difficult to provide clarity and remain succinct. Below we’ll look at two examples of titles that didn’t quite meet the mark and see how we might make them more clear.
In the above example’s original title, it wasn’t clear what about the header the issue was. It gave a sense of where it could be found but not what the problem was. Upon opening the ticket and looking at the screenshots, we see that a CTA’s copy on the first step doesn’t match the subsequent page’s heading.
In contrast to the first bug we looked at, the title provides more information on what is happening but doesn’t tell us where. The screenshot again reveals the full issue but it’s our goal to tell the reader this upfront.
Structure your description
Now that you’ve written a crystal clear title lets move into the description which provides the space for everything else you’re conveying. I find it helpful to break this space into three main sections: 1) overview 2) steps to reproduce 3) intended design. This structure helps ensure the needed information is included and breaking it into distinct sections makes it more digestible.
Overview
In this section include details that maybe couldn’t be included in the title. This section can also include screen shots or screen recordings of the issue.
Steps to reproduce
Assume the person working on your bug has no context or idea of how to get there. Include the actions that were taken to to cause it. Steps to reproduce can vary widely from something as simple as it’s always like this to edge cases that require specific conditions such as input errors or issues that only appear on certain browsers or screen sizes. Pairing visuals with a written account is often best and can be done like step A causes step B. Tools like Kap are helpful to make gifs/movies that can either be included directly on a ticket or linked to via Google Photos or another similar tool. If possible try to determine if something is more general and if so you don’t need to include all details such as device and browser version.
Intended design
Here’s where to include what the product should be. Use a combination of written intention, design files, design system documentation, and any new documentation you created. When possible use commonly shared language within your team such as exact design system component names.
Use written intention, links to design files, links to design system documentation, and sometimes requires new documentation. When possible, use language with can be easily understood and maybe references things like your design system. Using these words in descriptions will make implementation more straightforward.
Grouping
Grouping similar bugs together can help reduce context switching as bugs are worked on. It typically takes less time to complete a single bug with five related parts than it does five separate bugs. Common examples of appropriated use cases include typography changes, a component incorrectly used across multiple screens, or incorrect copy.
Above is an example of two modals that both use buttons that aren’t the correct type. One option would be to write two different bugs or, perhaps better is to combine into a single bug.
Be careful not to get too bloated. When working on a tight timeline when perhaps not all bugs can get addressed before launch, pull ones out that are higher priority. For example you have a number of copy bugs but some appear on main flows and others are extreme edge cases.
Ready to write
Seeing your work built is one of the most satisfying aspects of designing. While writing and following up on bugs is probably one of your least favorite jobs, it is an essential step in the building process. Hopefully these simple rules will improve the way you write bugs and help make completing them easier for your engineering partners.
Interested in joining the Lyft Design team? We’re hiring.
