Engineering

Dos and Don’ts of Bug Reporting

November 18, 2024

Ever had a grumpy dev throw a “need more info” your way? Or maybe you’re just generally curious how you can score a few points with your dev team by submitting the most excellent bug reports out there.

Of course, the best bug reports are the ones that have everything the devs need but are still short and easy to read. But what do the devs need? Well, you could always ask them of course, but they’ll probably be happier if you informed yourself in advance. That doesn’t mean you shouldn’t talk to your devs of course. Because after all, you and your team definitely should agree on a consistent way to report bugs.

But where to begin? To get you started, here are some “Dos and Don’ts” to consider while documenting your experience with bugs. Please note that I assume you are already use a tool to report or track your bugs, because if you still email bugs or god forbid use physical paper, then I’m afraid you have a bit more work ahead of you.

Do …

.. keep it simple, but not too simple.

Your title and description should be to the point and easy to read. But be carfeul, you don’t want to be too cryptic with your words. Of course, sometimes a simple “wrong font” can be enough, but only if both parties know exactly what should have been the correct front.

.. keep in mind that someone has to understand the exact problem you’re describing.

Never forget that you’re sending your bug report to an actual person who needs to quickly understand exactly what went wrong. It’s incredibly easy to slip into writing vague statements about what went wrong. But a neat trick I like to use sometimes is to pretend that I have to explain the bug to somebody in person. That way I can keep myself in check whenever i start rambling mysteriously about a strange bug I found.

.. include the essentials.

That devs are pressured to get lots of things done in a short time is not a secret anymore. For this to be somewhat achievable, devs should always have the correct info in the correct amount to quickly get started without any double or triple checking facts. But especially regarding bug fixing it’s even more important that everyone tries to leave as little room for misunderstandings as possible as the devs probably don’t have the time to chase after info every time there is a problem. Therefore, focussing on the most essential information like “What, where, when” either makes or breaks a bug report. Additionally, if your tool doesn’t already make you include your contact info then writing down a way to contact you is always a good idea.

.. try to reproduce the bug on your own.

It’s way too easy to forget trying to duplicate bugs when testing. I forget to plenty of times. But a bug can only be fixed when it can be reproduced at a certain reproduction rate. If there’s no way to reproduce it and it’s not a system critical bug, it might just end up in the backlog to be forgotten.

.. categorize bugs.

If your tool allows tagging or ranking by priority or severity, then make sure to use it. Being able to swiftly filter all bugs is incredibly handy as your dashboard grows in size. Lacking use of tagging occurs especially often with clients, so don’t miss out on that front as well.

.. use attachments.

With ever more powerful frameworks come more variety and more room for errors. Therefore, it’s even more important to use everything at your hands to point to the exact problem you’re experiencing effectively. This way, developers have it way easier identifying the cause and solving the issue.  Especially weird and strange bugs absolutely need some type of visual media and ideally logs to locate the cause.

.. say what you expected to happen.

Outright saying what you expected (in a respectful manner) can help devs understand what you wanted to happen, which can be valuable for them since they might have a different perspective on software or interfaces than you do. Especially when things get a bit crowded in interfaces, stating what you expected can be quite helpful.

Don’t …

.. artificially lengthen your text.

Writing more text for the sake of having more words is almost never a good idea. If your devs ask you for more information, then they mean they want more essential information – not just more words.

.. report more than one bug per report.

If you encounter a second bug which happened immediately while or because of the first bug, make sure to report it as a separate ticket instead of adding a few lines of text in the first one. This not only allows you to document both bugs more thoroughly, it also helps developers address, manage and fix both bugs easier.

.. submit a bug report that’s already in the system.

It’s certainly not ideal for everyone, especially clients, to have access to the bug dashboard. If you do have access however, make sure to check the board before you start your testing process. It could very well happen that some of the bugs you encounter are already known.

.. mix up bugs with feedback.

If your team has no agreement on including feedback into the bug dashboard, then you always have to make a distinction between feedback and actual bugs. Including suggestions or comments into your dashboard will more likely annoy devs than actually help them. Best collect your feedback separately and offer it as an addition to your reports, rather than mix it all together.

Related articles

See all articles