5 Layers Of Information Your Bug Tickets Should Include
Bug tickets should have a baseline of information
Break down traditional QA silos and empower developers to own quality checks.
In an idealistic world, bug free software would be the dream. Write the code, fire it up and have it work seamlessly the first time. No need to re-work, re-evaluate and re-test.
It’s nice to dream, however, the reality for every team is that software bugs do eventually find their way to production. Being able to document those sneaky bugs with all of the right information is important to help reduce the information gap that some teams may experience. We’ll look at 5 layers of information that your tickets should include as a baseline.
First Layer
An obvious one is a title. The title is the first thing the reader sees before they open expand the body to read the remainder. A good title should be a high-level representation of what the reader can expect in the ticket.
As the first layer, the title should provide a key piece of information. The reader should be able to look at the title and gain the following as an understanding: which part of the software is buggy, is it something visual, or more technical, and all without having to expand to read the details.
Titles can become long where some extreme cases have 10+ characters in them. And title with too few characters reveal nothing value on the surface meaning it’ll always need to be opened. An optimal level would consist of 5–7 words.
A good example might be: “Hero image missing on homepage mobile resolutions” versus “Hero image missing”. From the title, we understand it’s a visual bug, the homepage is affected, and it’s isolated to mobile resolutions.
Second Layer
Our second layer consists of the description. Descriptions are a place of context and background information. Bugs can vary in complexity which can sometimes dictate the length of paragraphs. Be strict with the word count. It’s easy to get carried away with details that may feel important, but on second glance is just noise.
The description should expand on the title, provide background, and only include the additional key pieces of information required. Descriptions tend to be skimmed through, so choose your words wisely.
My first suggestion would be to keep descriptions under a single paragraph. Bullet points are great for breaking text up and keeping order. Keep it factual and don’t ramble. Remember that bug tickets are no time for writing novels, get to the point.
Third Layer
Our third layer is all about listing the steps taken to reproduce the bug. It’s important we include this within our bug ticket so that anyone can reproduce the bug reported.
A couple of suggestions to help with the third layer: use a numbered list and avoid describing the steps in a paragraph. Don’t assume others know how to navigate the product, list the order step by step.
An example might look like this:
- Using Firefox.
- Go to https://blah.blah-blah.test/blah-blah
- Click menu option A
- Click sub-option B
- Nothing happens.
It’s a good idea to follow the steps you’ve just listed to ensure you have all the steps properly listed. If we had used a paragraph the end result will have been the same, but the readability isn’t as great.
Fourth Layer
The fourth layer is all about providing a screenshot or a screen recording of the bug. UI bugs are quite common and sometimes the way something has been described allows for ambiguity. We can eliminate that guessing game by providing a screenshot of the bug we’re observing.
Screenshots are a great way to show the exact component being described, and as well capture the bug. When including screenshots, having a box or an arrow in the screenshot can help shift the readers attention to where you need.
Screen recordings are useful in situations for bugs that happen intermittently or for bugs that are hard to reproduce/explain. Some recordings can go beyond a minute, so make sure you include only what you need.
Fifth Layer
And last but not least, it’s a great idea to describe the expected behaviour versus the actual behaviour you experience.
Just like the layers above, be precise and to the point. Apply the same tips by ensuring not to ramble on. Utilise bullet points to make them more readable. If you don’t know the expected behaviour, then reach out to who should and fill in the blanks.
Bug tickets aren’t complicated, but taking an extra minute or two by including the right information can save time down the line. Each of the 5 layers exists to support one another. We aren’t perfect so eventually we tend to forget certain details as time passes. A well-defined bug ticket can act as a time capsule and help remind us of those key details we may have forgotten.
There’s no perfect type of bug ticket and these 5 layers aren’t the only ones. Use these 5 layers to create a consistent way of working with the information that’s included in them. Start with these 5 and add the additional layers as your team needs.
Subscribe if you like what you’ve read? Leave a clap 👏 and stay tuned for more!
