Dos and Do Nots of a good web bug report
In my day, I’ve received no shortage of bug reports. Generally speaking, I build web apps, so these are bug reports that have to do with problems found on a website - either public facing or else internal administrative pages. I get a lot of bad bug reports that generally cause me to spend time tracking down information, this often involves getting back in touch with the originator of the report, making them spend more time explaining it. This is a lose - lose - lose situation - it takes time from me, takes time from the originator and causes the bug to be fixed more slowly than it has to, in many cases much more slowly if it takes awhile to get back in touch with the reporter.
On the other hand, a good bug report is a thing of beauty to behold. It provides the developer with all the context and details to figure out what is wrong. So, I thought I’d give a few guidelines on what I don’t like to get and what I do like to get in a bug report. I mean… you know… not that any code I write has bugs in it… I just heard from this other guy I know…
The basic guideline is be specific. There’s no science to it, it’s an art and a learning process for everyone - nobody who isn’t a developer is expected to know from the get go what they should list in a bug report. To that end I’ve listed some specifics below:
Dos (please!)
· Provide URLs
Provide URLs for examples of problems you are seeing. If it’s a public facing page, even if it’s generic, provide a url. If it is a problem with the content (or if you are unsure) provide a url for the admin page you used to update the page. This is a really helpful one - URLs make it easy to know you are on the right page looking for the bug. It also makes it easier for the bug reporter to verify that it has been fixed since it’s guaranteed that both parties are working with the same page.
· What it should be if it was right
Saying something is wrong or broken many times isn’t enough. Point out what is wrong (this text is showing up bold) and what it should be (it should be italic instead). This is very important - not just to know what the problem is but what it should be. Sometimes this isn’t necessary - if the page is broken, obviously it needs to be fixed. Nevertheless, sometimes things that look broken to you who are really familiar with the content and how it should be, do not look broken to the developer. This is especially true of style changes.
· Provide screen captures if it’ll help
This mostly applies to style fixes. Sometimes they are a little more complicated to explain - images are overlapping text, etc.. Rather than trying to explain something, it may be easier to simply take a screen capture of it and type up the location of the problem (see the upper right hand corner, where the two text columns are overlapping?). In some cases a picture is worth a thousand words.
· Error messages
If you are getting an error message either from the browser or from the website itself, it’s generally a good idea to copy and paste the message into the email rather than paraphrase. Sometimes there’s good information in the message that can get lost in the translation.
· Context
Sometimes it’s good to provide a little bit of environmental detail on the problem. Not every detail or every problem. If, for example, you have a site that allows you to login, it’s often useful to say whether you were logged in or out when you saw the problem. Or if you happen to be using a browser you don’t typically use and noticed a new bug, give the browser you’re using. If the problem is intermittent it could be useful to know what page or actions you were doing just before you got the problem. Think about anything unusual that you may have been doing prior to seeing the bug.
Do Nots:
· “The website is broken”
If the website is not actually down do not send this report. I used to get this one a lot, fortunately not so much any more. I’d get that email and breathlessly point the browser to the website which would be up and running, flawlessly as far as I could tell. Sometimes a particular page would be broken or some strange html flaw was showing up somewhere - I would only discover what after getting back in touch with the reporter.
· “this page is wrong”
This one is more common, and again, it doesn’t help. Wrong it what way? Sometimes it’s a browser/html issue. Sometimes, the text is missing. What is obvious to you, is more often than not, not obvious to the developer. Specifics!
These are just some ideas. It is not a checklist. Not every problem needs all these things, but almost all of them need some of them. If you are submitting reports and it’s taking a long time to get them fixed or if you find someone coming back to you repeatedly for clarity, try adding in a little of this special sauce to your reports. It’ll save you time and help bugs get fixed more quickly and efficiently than they otherwise would.
