Considerations on Bug Reporting in Teams

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:

• Trello
• Stack
• Sifter
• Waffle
• Basecamp
• JIRA
• GitHub Issues
• Asana
• BugHerd

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:

• GifGrabber
• PicGIF
• LICEcap

(Screenshot / GIF / Video) + Cloud Storage tools:

• Droplr
• CloudApp
• Screenr

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.