Good Bug Reports Increase Team Productivity
tl;dr
Bad bug reports cost your team time. Write and demand good bug reports using this checklist
- Short specific title
- Numbered steps to replicate
- Description of failed expectations
- Include your thoughts only at the right time
- Choose correct visual aids (screenshots vs screencasts vs nothing)
- Get your whole team on board
Good Bug Reports Make Your Team Productive
A team that knows how to write a good bug report is more productive. Period.
Have you ever watched two teammates go back forth for hours, days or weeks just trying to understand each other on a bug report? Have you ever been one of those teammates?
If so, you’re not alone. This happens at organizations of all sizes. Luckily there are plenty of solutions to make sure this doesn’t happen – or at least doesn’t happen too often – with your team.
Here’s the truth:
Making sure your entire team can write a good bug report can save you hours on each product release – or even days if you are working with a remote team or across time zones.
And that means getting your product or new features to market faster and, of course, with fewer bugs.
This post will discuss why good bug reports are so important to productivity. Then we’ll give an in-depth look at how we handle them at Ghost Browser. We’ll expand on that to discuss other methods for handling them at companies that aren’t small and remote like us. Finally, I’ll discuss a lot of tools you can use to make you, and your team work faster through better bug reporting.
This is the definitive guide to bug reports, so if anything goes un-answered, please leave a comment.
The Cost of Bad Bug Reports
Why are good bug reports so important?
That’s simple. Because the cost of bad bug reports is high.
Let’s look at the life of a bug report in general to illustrate my point. I want you to read the list below and pay attention to how many people have to ‘touch’ a typical bug report. This will help you truly understand the cost of a bad bug report.
This example is a for a website bug, though it’s not much different from a software bug life cycle.
- Someone finds a bug, writes a report and submits it to a developer or team of developers.
- One or more developers read the report.
- One or more developers work on a fix and commit the code to a development server.
- One or more QA testers read the report, test the fix and hopefully mark it resolved.
- The fix is pushed to production, where one or more QA testers read the report and test the fix again on production.
- The report is finally marked fixed and the original reporter re-reads the bug report and makes sure it satisfies them as a final step of QA.
Now, let’s be real:
That example has AT LEAST five touchpoints. But that idealistic example is not really how bug reports work. They are rarely that smooth.
In the life of a typical bug, there are a lot more touchpoints.
- At least one Project Manager will skim bug reports – often several times per day.
- If you’re in an agency, your clients might be doing the report skimming and even testing for replication.
- Many bugs are passed off from one dev team to another, from generalists to specialists or from senior devs to junior devs. More touchpoints.
- Who writes customer support documents at your company? They are reading that initial bug report too.
- What about internal documentation. That’s another touchpoint.
I think the point has been made. There are a lot of touchpoints. Now let’s look at how bad bug reports can lead to more time being spent on each touchpoint.
Common Mistakes in Writing Bug Reports
While a bug report that says “The new thing on the home page is broken” is better than nothing, if you are working on a team, you owe your team a little more help than that. Here are the top 5 mistakes I generally see with bug reports.
Title is too Vague
“Bug with new feature” is not a good title because by the time it gets fixed (if it’s a low priority bug), it might not be a ‘new’ feature anymore. The developer working on the bug might already have two new features under her belt when she sees this, so opening the ticket and reading is the only way she’ll know which feature is broken.
Also, use of the word “Bug” is not necessary. On our team, we do put “Bug” in titles of Trello cards in our workflow, but that’s because we put bugs and new features on the same board. If you use a bug tracker though, the very fact that you are submitting a bug makes the use of this word redundant.
Title is too Long
In most workflows, your bug report will be one of dozens – or more – that show up in a list of reports. That list will be scanned by project managers, lead developers, clients and stake holders who are trying to get a sense of the bigger picture.
It will also be scanned by other people submitting bugs to ensure that they are not submitting an issue twice.
That’s a lot of scanning so make the title scan-able! (Details on that below!)
No Steps to Replicate
If you hear a funny sound in your car, you need to tell the mechanic what to do so he can hear it too. People are really good at this. “When it’s cold out and I first drive my car, there is a loud screech but it goes away after 5 minutes of driving.” (You just need to replace the timing belt).
“When I turn right, there is a ticking sound coming from my right front tire, but I don’t hear it when I turn left.” (I have no clue what that is, but I’m sure a mechanic would – or would at least know where to look).
The point is, those are great bug reports. Sort of – they are great because any mechanic can identify the problem or at least replicate it so he can hear it himself from that report.
In software, it’s a little more methodical than that:
More on that below.
Telling Instead of Showing
The best way to demonstrate a bug report is to let the person who built the system stand over your shoulder while you make it happen again. And in an age when remote work seems to be the rule rather than the exception, that’s not always possible.
The next best way to make sure you are understood is to write as much as you possibly can, include the emotions you felt at every step of the process and describe the affect it had it on you even after you returned home. Roughly 10 pages would be perfect for this report.
Just kidding of course. No one wants to read that. And probably no one will.
A picture is worth a thousand words though – and a video is worth even more.
Why spend 20 minutes typing out a really long report when you could spend maybe 30 seconds to a minute recording the bug? As long as you have a text summary and steps to replicate with the video, this goes really far in helping developers understand all of the conditions around the appearance of the bug and thus, why it’s happening.
Description is Too Long
Remember every bug report will be touched 5-25 times or even more. Every time it has to be read, takes time that cuts into your team’s productivity.
Provide all of the information, but don’t be wordy or provide unnecessary details like your emotions about the thought process you went through to arrive at a decision. It just confuses the real issue which is replicating and fixing the bug.
If the thought process really is important, put a quick note about it – especially if you expected one thing to happen, but something unexpected actually happened. But don’t use the bug report to lobby to have it fixed. Assume the developer cares, keep the report short and give it a priority. If they change the priority, then you can go to bat for it. And don’t over-emphasize if you were frustrated or angry. No one really wants to hear that about something they built. It’s like calling someone’s kid ugly.
How to Write a Good Bug Report
A good bug report has the following characteristics. Master this, and your PM and the development team will love you, prioritize your bugs over everyone else’s and catapult your career to places you never imagined it would go!
Well…I can’t actually guarantee that. You will get more bugs solved in less time and keep a good relationship with the coders though – I can guarantee that.
Here they are:
- A short but specific title
- Steps to replicate the problem
- Your failed expectations
- Relevant visual aids
Seriously. That’s all that stands between you and all the glory of being the best bug reporter at your company. With just those four things, you can arm your dev team with all they need to squash any bug.
Now some of these items require more work than others. So without further adieu, let’s dig into them.
A Short But Specific Title
A bug report when you are writing is a bunch of words on a blank screen. But once you submit it, it becomes an object that is passed around, skimmed, organized and re-organized.
To respect that when writing your title, you can use the Menu Method.
Here’s how it works:
If you went to a restaurant and saw ‘Pig’ on the menu, you wouldn’t know if you want or not. You’d probably ignore it in favor of something more understandable.
Likewise if you were scanning the menu and saw ‘The muscle from the spine of a pig’ it would take you a minute to figure out that the restaurant has pork tenderloin…and you’ll probably be a little grossed out at the all-to-detailed description.
Use the Menu Method to make sure your report has a scan-able and easy to read title.
Title Templates
Bonus if your company uses title templates.
Testilio suggests putting the component that is being reported in brackets at the beginning of a title.
So a report would look like this:
[Signup form] Missing Error Message for Improperly Formatted Email
You could add other components to your template too including platform or browser. So then it could look like this.
[Signup form] Missing Error Message for Improperly Formatted Email (Safari)
Depending on your bug reporting software, those brackets could be a great way to narrow searches when you are looking for all issues related to a certain component.
Every project is different but title templates improve scan-ability for project mangers, developers and QA Testers.
Even if your team isn’t using title templates, you can. Remember, you’re trying to help your team do their job and they are going to pay more attention to your reports if the reports are consistent and easy to deal with.
Steps to Replicate the Problem
Notice it says ‘steps’ and not ‘a long paragraph with a lot of unnecessary information’. A numbered list is so much easier to read and follow than a paragraph – remember, each report has a lot of touchpoints and they should not all require reading of a paragraph. Use numbered lists!
And even more importantly, write them out as you are replicating the bug again. You should ALWAYS try to replicate a bug at least twice before submitting.
Why?
Because you might be working on a development server. Or you may have been logged into an app as an admin when trying to test as a non-admin. There are a lot of reasons why your test could be invalid so make sure it’s really a bug before you submit it.
In fact, you should clear your cookies, clear your cache and totally reset your testing environment to zero before you start a test. Often in Ghost Browser you would just need to open a fresh Session. Without Ghost, you could try a different browser.
Whatever tools you use, make sure you:
- Reset your environment. (Clear cookies, clear cache, make sure your software version is up to date and using the right server, etc.)
- Try to replicate the bug for yourself.
- Write each and every step into a numbered list.
Often in the process of replicating the issue a second time, you will see that there were conditions that created the appearance of a bug that was not actually there and you’ve saved a lot of people a lot of time chasing false leads.
Your Failed Expectations
This is where you provide two pieces of information:
- What you expected to happen.
- What actually happened.
A lot of bug reports only mention the second item. Imagine a Facebook user that reports “I added a new photo but it’s still showing the old photo!”
You can imagine the developer working on this bug has some questions, the biggest of which is probably “Where were you trying to upload it?”
Status update? Cover photo? Profile photo? Business page? Did you upload it to your blog and share the link?
Take this as an alternative:
“I uploaded a new photo to my blog post then went to my business page. I expected to see it as the photo in the post I had pinned to the top of my business page but it was still the old photo.”
Great. This is just user error – you need to re-share the post. Tragedy averted!
But, since the developers can’t read your mind, help them understand what you think should have happened. This lets them narrow down the possibilities from every type of photo you can upload to Facebook to a post image that is being automatically pulled from a shared link.
With the first example above, it would not even get routed to the correct team, let alone get fixed or be explained.
Relevant Visual Aids
If a picture is worth a 1,000 words, how many is a video screencast worth?
The answer is: It doesn’t matter.
What matters it how much time it can save your team.
Show don’t tell. A 30-second video will have the advantages of:
- Only taking you 30 seconds to make.
- Letting the developer see things that you are doing with your mouse or keyboard that you wouldn’t think were relevant.
The one disadvantage with video is that it is not scan-able. So you can’t just put a video link and consider that to be the entire ticket description. It’s also not searchable. If you put a 30 second video that discusses registration form validation errors into a ticket, but never put the text ‘registration form validation errors’ in the text of your ticket, or card, then anyone searching for that card will come up empty.
Screenshots are good too. They are a little quicker to make and often suffice.
However, another common mistake people make is using screenshots when they should be using screencasts. Don’t use screenshots to show a series of steps. Use them only in cases were the result of your actions is important but the process is not important or is commonly known. Even then, a screencast might be better. So get used to them.
It actually takes longer to stop and do screenshots and save them all to a common location, then upload them in order – plus most computers do not, by default, make it easy to view multiple images side by side.
Tell Your Team About This
Every team has its own requirement for bug reports, but sharing an article like this is a good non-confrontational way to get your whole team on board with improving efficiency through better bug reports.
Share this article with your team and enjoy the time savings and lower stress of great bug reports!