How to report software bugs like a pro

Virtually all software applications contains bugs - especially the first, early iterations of new products and most likely new features that get added on thereafter. As a software agency we ourselves have observed this in other people’s code that we review and – although it might surprise you to hear this – in code that we write too, at least in the earlier stages.

The focus for any good software house or product owner is to identify and eliminate as many bugs as possible. While choosing the best technology, the most appropriate language and opting not to roll-your-own code are all things that help during the early stages there are a number of additional things that can and should be done prior to any major release.

What is a bug anyway?

Before we get too deep let’s be clear on what we mean by a “bug”. It’s a bit of a catchall term that means any bit of code that does not execute properly. This might mean that it logs an error, the user is inconvenienced or, more loosely, it simply does not deliver the feature benefit that was intended by the owner.

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. (Wikipedia)

Why you should care

If you’re commissioning software then chances are you will be involved in testing what’s been delivered. Your primary objective may not be to spot bugs but you may well come across them while verifying that the software is meeting business requirements. For most product owners you’ll be taking on the role of a user. This pseudo-user experience might mean that you come across something that doesn’t work exactly how it should or is just plain broken. Being able to report that in an efficient, professional manner will help get the bug squashed with minimal effort from the development team.

When a bug is not a bug

We’ve already seen that the term “software bug” is quite broad. Indeed as the product owner you may well argue that it makes little difference what it is called and that you just want it sorted. It’s worth knowing however that some development teams might push back on a bug report and say something like “Not a bug, it’s a feature” or “This is business logic” or something equally mysterious. So what’s happening here?

Before software is coded there is often a specification which explains what users are going to do. These are called “use cases”. No matter how clear the specification document is there will always be edge cases and decisions that the developer needs to handle. Exampls of edges cases might be people using old browsers, entering strange text into a box or other cases that don’t quite fit into the use cases that you’ve allowed for.

For complex, poorly understood or badly explained use cases these decisions might be developed incorrectly. When you review the project you might see those when something unexpected happens; the developer has not made a mistake, they implemented what they thought you wanted but got it wrong.

It’s important to realise from a product owner point of view that inclusive support agreements can often get very confrontational on this point: Developers are rarely keen to untangle business logic that was badly scoped and does not represent a development mistake, especially at their own cost.

To get around this, product owners should always try to make sure that the development team understands as much as possible of what is trying to be achieved, both strategically as well as the user experience and how the use case they are developing ties into that big picture. After all, it’s best to avoid these edge-case bugs in the first place rather than wrangle over them.

Getting it sorted

Either way, there will come a time when you’ll need the development team to get it sorted. To do this efficiently they’ll need each bug reported with as much detail as possible. But what, specifically, does this mean? Here is a list of things you could tell the developer when you notice the bug:

Specify device and browser you’re using

Although browsers are much more aligned today than they have been in the past there are still subtle differences between them. Date selector problems in Safari, redirects in Firefox and autocomplete settings in Chrome are all a bit wacky. Your application might also be rendering on a mobile device which makes the situation more complex;

Outline your use case

Before you go too deep, firstly explain what use-case you were testing. Particularly for Agile builds this will help the development team align the case with their backlog. Normally this takes the form of As an <actor> I was <action> in order to <desired result>

The steps you are taking

Now it’s time to get detailed. What links did you click, what values did you enter into the forms? Being precise is key. Ideally developers are looking for “steps to reproduce”. Therefore, begin with what state your application was in (for example, were you logged in?) and then outline every action that you did.

Explain what did or did you not see

This is where most people fall down, so really practise this one! They get the steps to reproduce from above correct but then fail to explicitly state what they would have expected to see. In a bug report, never leave it to the development team to work out what the correct answer should have been after following the steps to reproduce, make it explicit.

Include screenshots and videos

If you want to get on your developer’s Christmas card list then send them screenshots or videos of what you did. This is as close to ideal as the average debugging user can get to providing the information that’s needed. Services like Loom, or TechSmith Capture can do this.

State the Priority

A font that isn’t quite the right colour won’t have the same importance as something that throws an error to the user. Therefore be clear on how you (as the product owner) rate each priority.

Finally, and most importantly, make sure you submit your information in a specific and agreed way. This could be by email but could equally be via Github, Gitlab or Bitbucket repositories. The latter are useful because they provide cross-team visibility on issues and allow for some dialogue which is especially useful if the use case needs confirming or there are other follow up questions. Getting an “issue number” is always nice and comforting and also allows you to refer or track issues as they - hopefully! - get resolved.

Automatic Monitoring

It’s worth giving a shout out to monitoring software like Sentry, LogRocket and LogDNA. These are all great tools that mean your development team can monitor your application and see bug reports without you getting involved. That said, they are limited in their scope and are no replacement for product owners verifying the user experience and business logic.


Bug fixing is an expected and necessary part of software development and is why many schedules build in time for significant user testing both during the build process and prior to deployments. Make sure you work with your developer to sort out these bugs and have a good repository and methodology for evaluating and fixing each one. Contributing good bug reports to that process, if done correctly, can significantly reduce developer time and cost and make this process less painful.

« View other resources