6 easy ways to improve your bug report descriptions

Posted by Justin Runyon on January 31, 2022

Half the battle of QA is finding issues with your product, but the other half of the battle is often the really tough part: communicating the issues to the developers in order to fix them in the bug tracker.

Here are 6 easy ways to improve your bug reporting descriptions in order to communicate more clearly to the development team.

Start every bug reporting session with this mantra: “The developers cannot read my mind”

Oftentimes the frame of mind you have when starting any type of work is what will lead to the most success.

For a great QA session to be successful, it helps to reset your mindset to think with the receiver of the feedback in mind. Then, you avoid assuming that the reports your writing are going to be understood perfectly by the intended audience.

Answer two important questions: “How?” and “Where?”

After practicing your mantra of “The developers cannot read my mind”, make sure every single bug report is centered around these two questions:

  • How?
    • Describe exactly what you were doing when you encountered the bug.
    • Example: “When clicking on the ‘Find Location’ button, I am not taken to the location finder tool.”
  • Where?
    • Where exactly did the bug happen? Use other elements of the page, design knowledge, etc. to give a precise location to the bug.
    • Example (improving the above example): “When clicking on the ‘Find Location’ button at the top of the page under the topnav, the button sends me to a 404 error page.”

Lucky for you, a bug tracking tool like BugCatcher makes the “Where?” question so much easier to answer because you can click exactly where the bug is occurring on the page (and we include the exact page automatically, too!). So, you just have to worry about the “How?” and describe exactly what you were doing when you encountered the bug.

Clearly mention the steps needed to reproduce the bug

Related to the above tip, this is how to write a better “How?” to give as much information as possible to the developers in order to make defect logging as understandable as possible.

Here’s a bad example of this:

“Pizza image doesn’t look correct on the page.”

Here’s a better example:

“The image of the pizza on the left side of the page should match the sizing of the image of the salad on the right side of the page. This is found halfway down the page when scrolling and is next to the title: “We’ve got the pizza you’re craving”.

In the second example, we’ve clearly identified how the incorrect image was encountered and how it should be fixed. If you’re using BugCatcher to gather feedback, this is done even more quickly and precisely

Don’t use a “commanding tone” when writing a bug description

This one is soft skill that does hard work for your team: when writing your bug descriptions, use a suggestive tone rather than a commanding tone.

For example, instead of saying, “Change the order of topnav items to ‘FEATURES | BLOG | FAQ | PRICING’ to ‘PRICING | FEATURES | FAQ | BLOG'”, you can simply put “Can we change the order of topnav items to ‘PRICING | FEATURES | FAQ | BLOG'”. It sounds silly, but after a long night or two of development, waking up the next morning and seeing suggestions instead of commands helps build better rapport between teams.

Use quotation marks to identify copy edits

This one’s not necessarily for the QA team, but perhaps for the product manager or client who needs to make a change to copy on the website.

Oftentimes, the copy that needs to be changed isn’t called out specifically, or it isn’t exactly clear what the new copy should be.

As an example, the feedback giver might write, Change See our menu to Order now.

Besides being tough to decipher grammatically, it’s so much easier to see exactly what needs to be changed by writing the exact phrases in quotations.

A better way to write the above would be, Change “See our menu” to “Order now”.

Now the developer knows exactly what the changed copy should be and how it should appear.

Of course, don’t forget to answer “Where?”!

Include the QA team in the daily standup

One of the easiest ways to make sure the QA team is on the same page as the development team is to keep the teams as close together as possible. This might be achieved by including one member of the QA team in the daily standup.

Many times, the QA team is kept completely in the dark. The thinking is that if they come at things COMPLETELY unbiased, they’ll do a much better job of testing according to the way a typical user would.

This is a fallacy, because no matter what, your QA team is likely going to already be more savvy than your general user.

So, the solution is to find a balance by including one key member of the QA team in the daily standup so they’re aware of the product’s goals and the objectives the developers are looking to meet. This QA team member will be able to better write bug reports because they know how they need to be communicating properly to the development team.

Later, for an unbiased user testing, you can include another member of the QA team to do another run-through.

Have some good QA/bug reporting tips of your own? Tweet us at!

Sound interesting?

Get your name on the list

Join the early invitation list and stay in the loop on development milestones. No spam. Ever.