Bug Reporting: What is a bug report and how to create good bug reports

At BugHerd we talk a lot about bugs. After all, it makes up half of our name. When we’re not herding bugs, we’re helping web development teams squash them, resolve them, sort them and manage them.

For people who spend so much time focussing on bugs, we don’t spent a lot of time answering a lot of the more basic questions about bugs. This all changes today. Right now, we’re going to answer some of your most pressing questions around bugs and provide results to searches we have received including bugs and bug reporting.

What is a bug?

What an excellent place to start! Let’s rule one thing out immediately, we’re not talking about insects. Apologies to all the amateur and professional entomologists out there.

When we at BugHerd talk about bugs, we’re referring to software bugs. So, what is a bug in software? I love a good dictionary definition.

If we turn to Wikipedia for the meaning of bug we find:

A software bug is an error, flaw or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways.

The Macquarie Dictionary takes it even further defining it so:

An error in a program or the machine itself, often undetected by the most stringent tests“.

However we define a bug, it certainly doesn’t appear to be something that we want in our software or on our website.

example of a bug report with a broken link on a website
Example of a bug report with a broken link on a website

Why do we call it a bug and not a problem, issue, weed or any other term from nature?

The term “bug” has been part of engineering lexicon since the 1870s at least. At that time, it mainly appeared in reference to mechanical faults. In fact, Thomas Edison himself wrote a letter in 1878 where he made reference to  “Bugs” referring to “little faults and difficulties” within machines.

Our favourite reference to bugs and computing software comes from 1946. For this story, we need to go back to the Harvard faculty at the Computation Laboratory where the Harvard Mark II was being built. The Harvard Mark II or Aiken Relay Calculator operators discovered a moth trapped in a relay that was causing an error. Rumour has it that they knew of the engineering term “bug”, so extracted the moth, taped it into the log book and wrote beside it “First actual case of bug being found.”

And now, we all quite naturally talk about bugs in computing and software.

Fine-tuning software for bugs
Fine-tuning software for bugs

What is a bug report?

We’re agreed that bugs in software = Bad. Bug Reports therefore are a way to say “Hey, this software doesn’t work the way it’s meant to, please fix it”. 

So what are bug reports? To define it:

A bug report is a document that outlines information about what’s wrong with the software. It lists the reasons or seen errors to point out what exactly is viewed as wrong, and also includes a request and/or details for how to address it.

A bug report needs to be clear, actionable and simple to complete. If it’s not, then no one will action or fix the bug, which in turn will mean no one will want to report bugs and we’ll all have buggy software.

Are all bug reports created equally? Of course not, and as always, it’s what’s in the detail that matters. We cover what makes a good bug report as opposed to a bad bug report in the question How do you report bugs below.

this is what the bugherd bug report looks like
This is what the BugHerd bug report looks like

Why is bug reporting important?

Nobody wants to work with software that doesn’t behave as expected. It’s a terrible user experience. Bug reporting helps smooth out software, so that it does what it needs to, without frustrating the people using it.

In fact, bug reporting is so important that many development teams have dedicated testers, or Quality Assurance whose job it is to find and report bugs. Have a read how Shopify Plus agency Juno freed up time in QA and UAT by implementing BugHerd to collect their QA feedback.

How do you report bugs? What information do you need to include in bug reports?

Reporting bugs doesn’t need to be difficult. Creating a great bug report means that bugs will get fixed faster too. So what do you actually need for a good bug report?

Here’s a 10 step checklist when writing bug reports to make sure you create good bug reports. 

Not all the information will need to be included all the time, but it will definitely help you to create a great bug report. 

  1. One bug per report. This is the golden rule of bug reporting. Each bug deserves it’s own bug report.Why? Because it makes it so much more difficult to resolve bugs when you need to hunt through a bug report that has multiple issues listed. Keep it simple, people!
  1. Where were you in the software when the bug occurred? Include the URL of the page where the bug is located if it’s a web application.
  1. What were you doing in the software when the bug happened? You may hear this referred to as steps to recreate. When a bug is replicable (able to be recreated) it’s easier to work out what went wrong and to fix it.
  1. What were you expecting to happen? If a bug is software working in an unexpected way, you need to say what you expected it to do.
  1. A screenshot or screen recording of the bug. If a picture is worth 100 words, including a screenshot or screen recording of the bug in your bug report may prove easier than trying to explain what you’re experiencing.
  1. Record technical information. Include information such as your operating system, what browser you are using for websites and web applications. Include whether you were using a desktop or mobile, if it’s not already clear.
  1. Include any error messages and codes you received. If you’re getting a specific error message or code, it will be helpful when pinpointing what the bug is and how to resolve it. Note, unhelpful error messages and codes can be minor bugs themselves.
  1. Can you replicate the issue? Does the same thing happen every time you try to complete the task you’re doing? Including this information in bug reports will help the developer find the cause of the bug.
  1. Have you tried to fix it yourself? Look, there’s a reason IT always asks “Have you tried turning it off and on again?” or whether you’ve tried refreshing the webpage you’re on. Include whether you’ve tried these simple tests in your bug report. It’ll save time on follow up emails or calls.
  1. How much is it impacting your work? How much a bug affects your ability to complete the task you want determines the order in which bugs are resolved. You may hear the term priority or severity used to determine how important bugs are and how quickly they need to be fixed. Typically severity varies from Very High (it stops you from working completely) down to Very Low (cosmetic changes). Including this information helps development teams prioritize the order they resolve bugs.

Is there software to help report bugs? Like a bug reporter or bug report system?

Thankfully yes. There are many bug reporters and bug report systems. There are numerous names used to refer to them:

  • Bug tracker
  • Issue tracker
  • Bug tracking tool
  • Defect tracker
  • Bug tracking software
  • Defect tracking software
  • Bug reporter
  • Testing tools
  • Bug report system
  • Bug report template

And numerous variations of the above. 

However you refer to them though, they make reporting bugs easier. The main purpose of any bug report system is to keep track of reported bugs.

They may differ in how they store and track bugs, in the quantity of information they store, in how complex they are.

The biggest differences though are in:

  • who they are designed for; 
  • what softwares they work best with; and 
  • what part of the bug reporting cycle they help most with.

What’s an example of a good bug report? Can you give me an example bug report template?

A good bug report contains the information from the 10 steps checklist above. With BugHerd, we do a lot of the work for you, by capturing information for you and helping you complete a good bug report.

Here’s an example of how BugHerd organises the information in a bug report. We think it’s pretty good, even if we do say so ourselves.

bug reporting template example from top to bottom
Key elements of a Bug Report, from top to bottom
AWhat is wrong and what it should be
BURL (location)
COperating system, technical information for replicating and solving
DScreenshot
ESeverity
FAdditional information

Conclusion

Bug reporting can be manual or automated. You may use a software, spreadsheet, emails or even face to face meetings to collect the bugs from your team or clients. Whatever you use for your bug reporting, we recommend to use the above bug reporting template that includes all needed information for your team to fix the bugs in question. 

BugHerd offers a free 14 day trial, so what are you waiting for? Upgrade your bug reporting and give it a go!

About Merrin - As Product Marketer here at BugHerd, Merrin loves talking about product, more precisely talking to customers about how to get the most out of BugHerd. With a background in writing and communications, you can bet she enjoys a good blog post with her coffee.

Comments are closed here.