Help! My website is broken! How to write bug reports that get results – Quickly

27th August 2017

how to write a bug reportFrom time to time you may find your website doesn’t work quite the way it should. Occasionally your app may start misbehaving – or not behaving at all. Broken websites lose business and need to be fixed as soon as possible.

Quite reasonably, when something goes wrong, the first thing most people do is contact their developer or hosting company with an email. In our experience, that message is often marked URGENT or EMERGENCY and contains comments like ‘website is down, needs fixing ASAP’, ‘app is not showing’ or ‘cannot update the website’.

Unfortunately, without more information, this is not the best way forward and may actually slow down the process of fixing the problem. So when you do have a problem, what is the best way to get things back up as quickly as possible?

How not to write a bug report

Your website is not working as you want it to. Obviously the way to fix it is by telling your developer or hosting company as soon as you can. Just send them an email and they’ll know what to do. Definitely mark the message as urgent or emergency – so they realise how important the problem is, drop everything and get to work.

As a development company and hosting provider we get one or two URGENT / EMERGENCY messages every month. When that happens we want to put things right just as much as our client does. We go DefCon 1. Our equivalent of the old Bat-Phone starts flashing, developers are pulled off existing projects and teams mobilised to solve the problem.

However…

If the only information we have is “Website is empty” or “App not working”, then unless a site is literally not doing anything, or an app has completely stopped functioning, we don’t have much to go on – It’s a real life needle and haystack situation.

A bug report like that gives us no idea where to look, or how to recreate the issue. Time is wasted trawling through code or trying to get back in touch with our distressed client.

Bottom line, it’s rare that we can fix an issue if we don’t actually know what the problem is.

This can be really frustrating and delay the process of putting things right.
For website owners it prolongs the impact on their business and could harm sales. For us – as a company who take customer service seriously and pride ourselves on the technical quality of our work – it can seriously slow down solving the issue.

We waste time searching for a bug, which we know is there, but haven’t got a clue where to start looking.

Secret tip: Many hosting companies have a 2 minute response time guarantee – but this often only applies to the first ticket received. To make the most of this, and ensure your developer can start work, make sure your ticket has enough info for them not to have to reply to you.

How to report a problem with your website or app

Sometimes, for many differhow to write a bug report for a broken websiteent reasons, things can go wrong. Could be an outdated plugin, high volumes of traffic or two lines of code that just don’t play well together.

When that happens we want to put things right just as quickly as you do. To ensure all that happens smoothly, it’s really helpful if we have a full description of the issue.

That way we can set up the site the same way you have it (on an iPhone 5 or in IE8 for example). From there we can follow your steps to replicate the problem and, usually, have it fixed in a flash.

A few of our clients have struggled with giving us this information in the past, so we’ve drawn up this little list of key points you should try to include in your bug reports. Follow these and you’ll be helping us to help you faster – guaranteeing your problem is fixed as quickly as possible.

*Preconditions*
*Summary*
*Steps to Reproduce*
*Expected Result*
*Actual Result*
*Workaround*

Let me illustrate these points, using a recent example we had with a client. They’d noticed that social share icons were not showing on the blog pages of their website.

Preconditions

We want to view the problem the same way you are in order to replicate any bugs.
In many cases website errors are particular to certain preconditions, which might include;

  • Using the app on a particular operating system.
  • Viewing a website in older browsers.
  • Registering as a user.

Summary

Next we need a brief description of the problem. Try to be succinct – so the person reading knows exactly what it is happening and when.

This could be something like; “On the news pages there should be sharing icons but they’re not there’’ or ‘’The app doesn’t function offline’’.

Steps to reproduce

This is probably the most important part of the bug report for a developer. It should detail the steps to be performed to replicate the issue? In our case it was;

If your developer can replicate the issue, it’s going to be much quicker for them to fix.

Expected result

This is what you should be seeing.

For example; ‘’I expected to see the Facebook, Twitter and WhatsApp sharing icons under each article’’.

Actual result

What you actually saw, or what is happening.

Something like; ‘’There were no social share icons under the article’’.

Workaround

Not vital. But if you have managed to work around the issue this is the place to say how – and it could give us some clues to fixing the problem.

In the case of our client with the missing social icons, they’d noticed that the issue only showed on Internet Explorer – one of the older web browsers. That really helped us. We knew exactly where to look and put things right in about ten minutes.

The takeaway

We want your website to work just as much as you do. If something does go wrong we’ll do everything we can to put things right.

Without all the details it can be difficult.
It’s a bit like telling a cook you don’t like their food without explaining why.

So the next time something goes wrong with your website or app, spare a thought for your developer and take a few minutes to make your bug report as detailed as possible. I guarantee, you’ll have your website fixed in a fraction of the time it will take if you don’t.