A template for better bug tickets
Using a template for writing bug tickets will ensure that you and your colleagues will include the important details. Those details will help to speed up finding the root cause as well as solving the issue.
Here is the template I’ve introduced in multiple teams in different companies.
The template
Title
Describe the problem in three words.
➡️ The problem has to be understandable from the title
What is going wrong?
Describe the problem you are experiencing as precise as you can.
➡️ The most important thing is to understand the problem and to know what is going wrong otherwise the engineer cannot come up with a suitable solution that fixes the problem long term.
What is the expected behaviour?
Describe what you expected to happen.
Describe what you wanted to do.
➡️ The engineer has to solve the problem in a way that fulfils what you describe here. The solution can only be discussed and validated if the outcome is clear defined. It can also lead to a discussion that can result in changing more than just fixing the bug but in rethinking bigger parts of the software.
Steps to reproduce the bug
Before starting to write the ticket, try to reproduce the bug again.
Make a list of pre-conditions and the steps (clicks, login / log out, upload/ download, input etc.) you did until the bug occurred.
➡️ When the engineer starts working on the ticket, the first thing they’ll do is to reproduce the bug with the given device/ tool and version. They have to fully grasp and experience the problem themselves so they can tell how it occurs and how to fix it.
Videos / screenshots
A pictures says more than a thousand words. It makes it much easier to understand your explanation when the engineer has some visual helpers
➡️ A video or screenshot will give the engineer even more context and helps them to understand the problem.
Device / tool used
This can be e.g. which mobile device (iPhone 13 Pro / Google Pixel XL/ etc.) or which browser (Chrome, Safari etc.) you used
➡️ The engineer has to find out whether it is a device/ tool specific problem or a general problem
Software version
E.g. iOS 16 — Version 2.3
E.g. Version 111.0.5563.146 (Official Build) (arm64)
➡️ As with the device, the engineer has to figure out if the bug is version specific or if it happens on different versions as well
Why do I need so much information?
A template provides an effective way to document issues. There are valuable for the person using it and even more valuable for the person reading and working with it.
And sometimes you don’t even need to write a bug ticket. Before you start typing, think about the following questions:
- Is it actually the program or app that is not working?
- Is it maybe just my network connection that isn’t stable? (Try if you can still call e.g. google.com)
- For apps or web-applications: Is the server reachable at all?
- Etc.
Sometimes the software we interact with doesn’t have a flaw but something else is going wrong and the symptoms of this just become obvious in the software we are using.
So, when you as e.g. a product owner or product manager or general user of an application find a “bug” think about where the problem might lie before taking the time to write a bug ticket.
If it’s based on user feedback. Take the time and try to reproduce it yourself. Don’t write a ticket for every customer complaint. Try to measure how often someone complains about it and asses if it actually is something that needs to be addressed.
Context is key
If you have identified that the bug is indeed within the software you are currently using, you can start to write a bug ticket. Here, context is the key part. Be as precise as possible about your actions and the pre-conditions that made led to the bug. For the engineer reading the bug ticket 3 things have to be clear:
- What you wanted to do (expected behaviour)
- What went wrong a long the way (behaviour)
- What you did to get there (pre-conditions)
Example
Imagine, someone wants to eat pasta and you give them the following recipe:
Boil water
Put pasta into the water
Cook the pasta
After the attempt they tell you “I can’t eat pasta because it is still raw. The recipe does not work.”
From your perspective the recipe is very clear on the instructions, right? So, what could have gone wrong? Think about possible scenarios. Was the water still boiling? Did you wait long enough to cook the pasta? Did you stir the pasta from time to time? What kind of pasta did you use? The list goes on. But unless the other person tells you what they did precisely, there is no way for you tell where your recipe was not clear enough.
As hard as it is for you, it’s equally hard for an engineer to pin point where or when the bug occurred. If it was a one time thing or if it is reproducible. Almost by nature engineers are quite curious and like to understand why and how things work or don’t work. But nothing puts a curious mind more of than a task that is barely executable because of a lack of information that could have been easily provided.
Why should you should write the ticket yourself?
Following this or another template helps and forces you to really think about the problem you are describing. It is a guide for you to structure your thoughts, put them in context and give a perspective on them. Sometimes, you’ll find that the problem you thought would be e.g. in the app is actually more backend related or that it wasn’t a problem with the software at all but a network issue etc.
