How to report a bug

In the world of software, bugs are a fact of life. Software developers rely on their customers to report bugs when they find them, and how a bug is described can make all the difference in terms of how quickly it can be fixed.

Generally speaking, a software developer needs to be able to reproduce a bug before it can be fixed. This means a list of specific steps is required, and following those steps should reliably cause the bug to appear. The developer can then iterate through those steps while testing possible solutions, and can check whether the fix is successful.

Even if the developer cannot reproduce the bug, perhaps because it is the result of a different hardware and/or software configuration on the part of the customer, having a list of specific steps that will reproduce the bug is essential because it can guide the developer towards identifying the cause.

This is what a useless bug report looks like:

Hi. I have bought your app it doesn't work. The car doesn't move. Please fix asap.


It's pretty much impossible to fix anything based on this bug report.

First, which app? If I don't know which app we are talking about, how can I fix it?

Second, which car? My apps tend to feature more than one car, so I need to know which one we are looking at. Is it blue? Red? Yellow? Help me out here!

Third, what do we mean by "it doesn't work"? This needs to be fleshed out into a description of what you are expecting to happen, what is actually happening, and what you have tried before getting in touch.

This is what a helpful bug report looks like:

Hi. I've installed your Road Board app, but it doesn't seem to be working. After launching the app, I tapped where it says "Car" and selected the Blue Car. It appeared on the screen but I can't get it to move independently. I can drag it around with my finger but that's it. A colleague showed me the app with the blue car driving around and demonstrating how to do junctions. I've tried adding other cars as well but the result is the same. I can't find a way to make them drive around. I'm using iOS 7.1.1 on a WiFi-only iPad Air.


This description only takes a minute or so to write, but it is infinitely more helpful and in this case leads to an instant diagnosis of the problem. Rather than a bug in the app, the user is confused about what the app actually does. He has seen a demonstration of a different app, and has installed this one expecting it to behave the same as the one that was demonstrated.

Because the bug report mentions that the app in question is Road Board, and because the user has described what he was expecting to see, what he actually saw, and how he got to that point, it very easy to establish that the problem is a simple misunderstanding. The problem can then be addressed quickly and easily with a simple explanation of the differences between the animated "Learn To Drive" apps, which is what the user had seen in his colleague's demonstration, and the Road Board app, which is what he has ended up installing on his iPad.

The information about the iOS and iPad version were not needed in this case, but it's good that the user provided the information because it is often relevant when troubleshooting bugs.

Here is another helpful bug report, this time describing an actual fault within the app:

Hi, I've been using your Manoeuvres app for some time with my learners. It was working fine until I installed the latest update around a week ago. Since then, I've found that the blue car sometimes flips upside down when about to do the parallel park. I've attached a screenshot so you can see what I mean. I can reproduce this issue by following these steps:
• Launch app
• Select Parallel Park section
• Tap "Advance" to show the POM routine
• Tap "Advance" again to get the blue car into position to start the manoeuvre
• Tap the "ORU" button to bring the purple car onto the screen
• When the switches appear for the controls, turn on the brake lights or the reverse lights
• The blue car suddenly flips, so it is facing the wrong way for the manoeuvre

I'm using iOS 7.1.1 on a WiFi-only iPad Air.


This report gives plenty of detail, including an exact description of how to trigger the bug and a screenshot so there is no misunderstanding about what is visible on the screen. Using this bug report, the developer should be able to troubleshoot the issue without having to request any further information.

The information about the iOS and iPad version helps the developer to pin down whether or not this is an issue that only affects certain users. It can also help the developer to reproduce the bug and test the effectiveness of the solution.

The current iOS version information can be found on your device by going to:
Settings > General > About > Version

You can submit bugs by filling out my online Bug Reporter form.