Photo of hands using a laptop giving a bug report

Giving great bug reports

Software bugs are an unfortunate by-product of software itself. As software becomes increasingly effective and efficient due to developers increasing functionality. This increase in complexity leads to the sad truth that there can never truly be a bug free piece of software.

Painful and burdensome as they are a bug’s effective disruption to the project/team/organisation/customer and product can be reduced through some acceptance that they’ll occur and a little planning to help streamline the process of initial discovery to ultimately fixing said digital gremlin. After all, a bug can carry with it costs both time wise and financially so speed is pretty important when you want to really focus on budgets and of course employee stress.

Here is why giving good bug reports is so important – software is complicated.  I’ll repeat that. Software is complicated.  Your bug probably isn’t obvious, otherwise it would’ve been fixed by the developer on the first pass through the work.  They probably aren’t stupid or lazy.  Saying in your bug report “It doesn’t work” really isn’t that useful.

Throughout the QA and development process it’s a great idea to use a Bug tracker.  A bug tracker is a piece of software to help track bugs and issues without resorting to emailing across hundreds of small bugs and issues at a time.  That leads to a big mess of unstructured communication and people getting unset when stuff goes missing, doesn’t get fixed, requires a bit of back and forth discussion or general continued interaction.  We use DoneDone as our Bug and Issue tracker.  It lets us have a list of all the issues in a project, give them priorities, tags, due dates, descriptions, assignments and then we can create release builds from DoneDone that notify testers where they can test bugs that we think have been fixed.  It contains the discussion of a particular bug to that bug so there shouldn’t be crossed wires or miscommunication.

The first goal of a Bug Report is to get the developer to see the bug for themselves so they can identify what’s going wrong.  If it can’t do that a good bug report helps the developer understand what went wrong so they can try and find out what is happening.

Giving Great Bug Reports

While time consuming to do a great bug report helps developers get on with their work and identify the source of the error as quickly and as painlessly as possible. Therefore…

Check to see if it’s already been reported

There is a good chance that a bug you’re experiencing is known about.  The developer themselves may have reported the error to the bug tracker to save it for later or another tester has reported it already.  Check the bug tracker for similar issues.  If your bug is already there add to the discussion and say you’ve had it happen as well.  If not, go ahead and report the bug.

Be Clear & Specific about what happened.

Over communicate.  Go into lots of detail about what happened.  Saying “it doesn’t work” isn’t very useful.  Your developers (probably) aren’t stupid or lazy.  They made it work for them so you may be approaching the UI in a different way or have come up against something they didn’t account for.  Tell them in your report exactly what has happened and what you expected to happen.  If you are reporting a visual defect be specific as well. “This looks wrong” doesn’t help anyone.  “The font in the heading is about three pixels too large on the homepage” helps a whole lot.

Provide Steps to Reproduce the Issue.

Unless it’s something trivial it’s unlikely your developer can fix it without making it happen a few times. Provide them with a step by step of what you were doing at the time and how you made the bug happen.  Then they can go through step by step and diagnose the problem.

Provide Evidence & Examples.

A Picture being worth a thousand words is particularly true when it comes to bug reports.  If you can provide  a screenshot or a video of what’s going on then you’ll save yourself and your developers hours and hours of time going back and forth describing the issue.  Particularly with visual errors and deformations, a screenshot of the error and one of the correct version can be invaluable.

Understand the variables

Again, your developers aren’t  stupid or lazy.  They probably think it’s working pretty well or they know its something to comeback to.  Therefore they are unaware of your bug.  There are many variables in software development (sorry, not sorry) once something has shipped.  If you’re viewing a website your operating system and web browser can have a big effect on how a page is displayed.  If you’re having an iPhone app built, which iPhone model and iOS version can have an impact.  Make sure and provide that information to your developer.

An Art Form

Giving a great bug report is an art form and a skill.  As software continues to take over more and more of our lives and get increasingly complex the need for people to give better and better bug reports is vital.  Learn how to do it well and your development project, wether its a website, a SaaS app or an iPhone application will go so much better.

Stewart Ritchie Lead developer and founder of Powered By Coffee. Stewart has been building websites for 15 years and focusing on WordPress for 5. He founded Powered By Coffee in 2011 after finishing is masters degree. He lives in Guildford Surrey with his wife Sydney and their two cats.

Signup to our mailing list