how to file a bug report

…on a web applicaiton, for non-technical people.

There is some skill to filing a good bug report. But not really that much, just a few tricks and tips. If you can give your developers or IT staff a good bug/problem report, they can understand the problem faster, not need to go back and forth with you on it, get to fixing it faster, and that means they can fix more of your problems.

  1. A screen shot is sometimes helpful, but not nearly as often as you think. It’s hardly ever helpful when all you send is a screen shot. You can ask your IT/developers if a screen shot is useful or not, or, sure, you can send one just in case.
    1. However, if you do send a screen shot, don’t send it as an MS Word document with an image in it, please. Ask your IT support staff to show you how to save your screenshot as an actual gif, jpg, or other image format.
  2. What is likely to be more or just as helpful than the screen shot, is the URL of the page you were on. You can ask IT support staff to show you how to see, copy, and paste that, if you don’t know how. Yeah, some web applications from our vendors suck and the URL won’t help either, but on a decent one it will.
  3. But you know what’s more helpful than either a URL or Screenshot, and if you’re only going to do one thing, what you should do?  Describe the issue specifically in words, with these three points:
    1. What page were you on when the problem occured, and how did you get to that page?
    2. What did you click on?  Or if it wasn’t a click, what other action did you take, like filling out a form, with exactly what content?
    3. What did you expect or want to happen when you did this — and what happened instead, that you consider a problem or bug?

That’s pretty much it. Not that hard, right? Describe those three things in words, and you’ll have made it so much easier and quicker for your developer/IT staff to get to the bottom of it, which means they’ll have more time to get to the bottom of more things — and they won’t have to get back to you and ask you more questions, saving your time too!

In order to get to the bottom of it, the IT person has to know how to reproduce your problem. Most bugs only happen in certain circumstances, or they would have been found and fixed a long time ago. It’s not obvious to anyone what those circumstances are, that’s what the IT person will have to figure out. So tell them exactly what you did to get there, so they can know they’re doing the same thing to trigger your bug. It’s also not always obvious to the IT person what was supposed to happen, or maybe they have a different idea of what was supposed to happen than you do. By telling them what you expected to happen, and what happened instead, then they understand what the issue is, and what it needs to instead look like to be fixed to your satisfaction.

Plus, your IT person will be so thrilled that you gave her or him a good trouble report, and then you’ll be so thrilled when your IT person finds a fix.

Bad trouble report: “The searching and exporting part doesn’t work right, here’s a screen shot [MS Word document]”

Good trouble report (made up incident): “I search for ‘german autonomism’, and the first record that comes up is ‘semiotics and art theory’ by Schecter. I click on it, and I get the record. Then I click on ‘export to Refworks’, and I expect to see the RefWorks export screen, but instead nothing seems to happen at all, I”m still looking at the record.”  If you want to throw in the URL of that ‘semiotics and art theory’ page, it can’t hurt, and sure, why not a screenshot, but you might not even need them.

This entry was posted in General. Bookmark the permalink.

2 Responses to how to file a bug report

  1. Probably guilty. With that said, I will pass this to my co-workers. Also, if you’re locked into a microsoft environment (with IE), you can paste the screenshot into ppt, crop and compress (to remove cropped areas), and then right click save as jpg. It seems roundabout, but if your computer is very locked down, it will still work.

  2. jrochkind says:

    I think most everyone that reports bugs to me has gotten pretty good at it, gradually, mostly, with occasional exceptions. This was not meant to be a passive aggressive critique!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s