Here’s a frustrating situation: someone notices a real layout bug or a glitch of some kind, but they fail to accurately describe the problem when they tell you about it. As front-end developers, and all-round good team players, it’s our responsibility to establish a workflow for reporting, cataloguing, and describing the bugs that people are likely to encounter.
Having a system for bug reports in a team environment has a ton of benefits:
- Knowing which bugs currently exist.
- Understand who is working on what (and what they need).
- Get an overview of how much time it will take to get things done.
- Find tasks that are blocked or those which require some kind of dependency before they’re tackled.
The first step is to pick a tool that everyone feels comfortable with
With a solid bug-fixing system in place we’re in a much better position to do great work, yet it’s important to note that good bug-reporting skills are not only a requirement for developers. Everyone on the team should be capable of finding a bug and providing as much information as possible about it. This means that designers, developers, and project managers of all experience levels shouldn’t be afraid to use the bug tool and get an overview of the project as a whole.
I’ve always found that Trello has been my personal favourite, as it makes a lot more sense to the rest of the team, but that doesn’t necessarily mean that it’s the best for your particular use-case. Here are some of the most popular bug-tracking tools and services out there that are worth checking out:
Regardless of the tool that we pick, in the end we need to ensure that everyone is happy with the proposed workflow since we’ll need everyone’s help in documenting, recording and scouring the project for potential bugs.
An unhelpful bug report
Even if you pick the perfect tool, it doesn’t necessarily mean it will be used by everyone in a helpful manner. There have been plenty of instances where I’ve struggled to find a reported bug because of the lack of information that’s been available.
Not very helpful:
- “the list style is broken in IE”
- “when scrolling across the page there are weird glitches”
In fact these types of comments are almost useless to a developer because they aren’t specific enough. Developers would much prefer that a bug report contained info such as the who, what, where, when and why.
A helpful bug report
Although this is completely dependent on the particular case in hand, it would be best to read something more along the lines of:
“the special list style on the Contact page is positioned incorrectly to the left side of its container in Firefox and IE11. Please see the attached image for more info.”
From here a developer can immediately find the bug in question and begin to devise a proper solution to the problem.
But how do we help everyone else on the team write great bug reports?
I’ve found it immensely helpful to sit down with everyone on the team at the beginning of the project and outline in detail how we should work with them. Who says when a bug is fixed? Who reviews which particular bit of code? Which automated tools should we use to find bugs? What assets do we need from the design team when they find one, too? These are important questions that can lead to frustrating problems if they’re left unanswered.
I’ve come up with a quick list of items that I expect from most bug reports:
1. Be short and to the point (but don’t be a jerk)
Ideally we want bullet points rather than long sentences so that a developer can find the issue as quickly as they can although that doesn’t give us an excuse to be curt. It’s best to describe the problem as accurately and with as few deterrents as possible. If there is someone who built that particular feature and knows the in-and-outs of it, perhaps you should assign it them first. But, don’t put all the blame on them.
2. Make sure to add screenshots and/or GIFs
For animation and complex interaction bugs in particular, animated GIFs are almost essential to highlighting the flaw’s peculiarities. However, for the most part, a simple screenshot will help us find which view or template the bug can be found in.
Animated GIF grabbing tools:
(Screenshot / GIF / Video) + Cloud Storage tools:
And don’t forget in GitHub issues you can just drag and drop screenshots:

3. Identify the browser version
It’s not very helpful if you simply quote the name of the browser like “Chrome” or “IE” it’s much better if you give a particular browser version such as “Chrome 42” or “IE8”. But, if you can also figure out whether the bug isn’t present in other browsers then that’s even better, something like: “I found this bug in iOS 8.3 but I can’t replicate it in any other Webkit browser.” With this sort of information you might save a developer a lot of time and they can more quickly identify what’s going wrong.
If you want to make sure you send along all the possible information, you could use a tool like Support Details that snags a lot of stuff and allows you to email it or PDF it (or just screenshot it to include). If you have a bug reporting for you control yourself, you can even grab and prefill hidden fields with this information so you have it without any effort from the reporter.
4. Make a note of which template, view or page the bug can be found on
If it’s on the /blog
or the /contact-us
page, or if it can be found in a specific partial such as the header or the footer, let the developer know that as quickly as possible.
A full URL is usually super helpful.
5. Don’t forget to mention the particular module or class that might be causing the issue
If you’re more familiar with the front-end and want to give a developer an answer to a problem you’ll need to do two things: First you’ll need to collect a high-five from every developer on the team because reporting bugs whilst simultaneously telling the developer how to fix it is a big deal. But secondly you’ll probably need to make a reduced test case. This involves breaking up the code into little chunks and picking away at it until you reveal what is precisely that’s going on. With this information you’ll be honing in on the section of problematic code and making everyone’s lives a little bit easier.
6. See if there are any console errors or notifications
Rather than copy/pasting the console error it’s probably best to take a screenshot if there’s any warnings. They might be unrelated to the particular bug you’ve found but it might just be the thing that’s messing everything up.
7. Double check if the bug has already been found by someone else
Duplicating bug reports generally hasn’t been that much of a problem in the projects I’ve worked on, but if there are lots of issues, it’s definitely worth taking a quick glance through the archived bugs or the currently open issues to see if your bug can be found there.
This task might also involve you going through and seeing which bugs are similar and tagging the problem in the app that you use. If the bug has been found then maybe it’s worth adding more information or noting on the card as to where you found a new instance of the same problem.
8. Group tasks into specific categories
I’ve found it particularly useful when marking an issue as ‘blocked’ by using the labels feature in Trello. A big red tag will let everyone know that there’s another problem associated with that task that must be dealt with first.
Similarly it’s helpful to separate everyone’s tasks into specific areas such as:
- Content
- Design
- Front-end
- Integration / Back-end
- Bugs
- Code Review
- Done
This gives us an overview of the project timeline and gives developers an opportunity to look at all the bugs with a single glance.
Most bug-reporting software has the ability to classify things. Tagging, categorizing, labeling, assigning, whatever.

9. Document your existing bug task workflow
If you feel that you have a great workflow in place then perhaps you should setup a document that covers your process with a little detail. This might not only be for your own organization and might help others so that they don’t make the same mistakes. Two references come to mind: the Thoughtbot playbook and Harry Roberts’ post on his Trello workflow
Wrapping up
I’ve always felt that a list of bugs shouldn’t be a daunting, over-whelming pressure which burdens everyone on the team with the desire to fight and bicker. Instead, a bug list should inspire us to roll up our sleeves and encourage us to help out in whatever way we can. So, if we spend a little time figuring out these tiny details of our process, perhaps we can shed all of those burdens and continue to build great things for the web.
What does your bug-review process look like? Which tools do you find useful? Add a comment below and I’ll be sure to update this post for future reference.
Maybe few other things could be handy:
Create bug report template so that everyone can follow it. This reduces problems with missing information.
Always add section expected results and actual results.
Maybe add trace logs from e.g. Fiddler.
Screenshots are good, but sometimes not enough. Consider recording video for some bugs to present it. It prevent from guessing what’s reporter thoughts.
Thanks so much for sharing your insights!
I guess the most important thing for bug tracking is a proper workflow installed. On the one hand, it must be super-easy for a QA agent or tester to file a bug report. On the other hand, developers need extensive information in order to reproduce bugs.
I have noticed a refreshing movement from ambitious startups addressing the painfully inefficient bug-reporting and issue-tracking process, since many “traditional bug tracking tools” lack some great user experience.
There are some great bug tracking tools out there nowadays which makes the process itself fun (again). If you take Usersnap (https://usersnap.com) for example. It adds information like screen resolution, browser version, installed plugin automatically to every bug report.
Regarding 6) console recorder: I truly recommend to check out the console recorder from Usersnap (https://usersnap.com/features/console-recorder). It’s a great productivity booster, since it automatically adds client-side javascript errors (or xhr logs) to every bug report.
Great, for an internal bug report, where someone might have this info available; or if they have the time, skills and knowledge you do, which can vary amongst a team… Instead, I would encourage SW devs to try to automate as much as possible i.e. what browser is being used to make the bug report (this is easily retrievable), the URL you mentioned is also a doozie, as is the view file for the developer to include in bug reporting tooling, request data etc.
What I am trying to get across is, it’s easy for QA, or maybe a SW Dev for smaller enterprises, to ask someone to give you more info, which usually frustrates them, however nice you put it; even if that is not your intention; especially if they file a bug report, ignorant of your internal systems or architecture. They might even try to be helpful, guessing at what might be causing a problem and you just send back, no, or not my problem.
As a SW Dev I’ve had my fair share of wasted time looking at poor bug reports, but as a business owner, I also know, sometimes people get lazy, or lack the skills / access to report everything in the most helpful way. Sometimes to get someone to fit your specific workflow for you, is you being lazy, rather than learn a potentially easier way for all involved. With this in mind, and with over 12 years professional experience, I think my suggestion of building the bug reporting into your SW and automating as much as possible is a good idea to help in these situations.
Also when reading a bug report, I’ve noticed a lot of “quick responses”, where people miss out things, such as (oh this is X’s problem, their CSS, their issue), when actually it could be an artefact of some poor CSS choices internal to the peice of SW using X. When I get back from Holiday, I will be instituting deliberate inefficiencies in my business QA, and support, because actually, if you have a support process in place, it’s there to help the user, and it’s a bonus if it helps the business as well, we all need to focus more on the user and their experience, and maybe then all of our products will be the most Kick-Ass they can be!
Defining a workflow is important but automation has been key in my experience. No matter how much I’ve asked for more information in the past it’s always been a struggle getting users to provide it. However, when I started using BugHerd, which does automate a lot of data collection (including a screenshot even), things got much better.
Only issue remaining that I haven’t been able to find a solution for is duplicates. When the whole PM team hits a site because we’re short on QA time I start to get all kinds of duplicates because people don’t pause for a moment to check and see if someone has reported it already. One approach for handling this to assign certain sections of the site to certain people but I haven’t had much luck. Still something I’m struggling with.
hey Chris,
it sounds like you need hashing, and an auto-complete where you can select & search other bugs, then merge / attach; I’m always furious when someone merges two bug reports & I loose information. Another way to do this is to have identifiers as a linked class to bugs (not parent-child), so that rather than resolve a bug, you resolve the identified action points, and by assigning the action points to the bugs, they by proxy are updated, sort of like a many-many.
On the screenshots, that is interesting, TBH we considered screenshots, but nothing seemed a good fit for a wide enough use-case, did you go the canvas route, or the browser-extension route?
I’d love to chat about this some time, you can find me on Twitter @LewisCowles1, and unlike your solution our bug reporting is in-house, and not for resale, so I doubt there is any conflict of interest.
And there’s also FogBugz, from the folks that make Trello.
Just saying.
I wish it was that easy. When you get a bunch of creatives and devs who have been told they can do no wrong and you point out something they did wrong… well let’s just say that unpleasant words will be thrown your way. Even when you document a bug step by step they will still fight you tooth and nail.
Thank you for these suggestions, I think they are very valuable. However, I see a slight problem where you suggest «Animated GIF grabbing tools»: they are only available for Windows or Mac OS X. Are there any similar tools for better OSes? :P
Ask and ye shall receive…
http://askubuntu.com/questions/107726/how-to-create-animated-gif-images-of-a-screencast
Should apply to any debian based distro, and has a range of choices…
Lewis, thanks for the link. :)
I really hope these resources (especially Silentcast, which looks the best) get integrated in the post.