Help Me Help You. What makes a great software bug report

September 13, 2017

Tom Cruise saying "Help Me Help You"At Itomic we love helping our customers.

We know that they love the convenience of being able to send an email to our support email address. This action automatically creates a support ticket for them. Thereafter, they can choose to continue the support conversation 100% via email. And/or they can choose to login to our support ticket system to view and manage all current and historical tickets.

But there’s a problem.

By allowing emails to be sent as support requests – instead of forcing clients to fill in structured online forms – the helpfulness of the information initially provided can vary a lot. Often our first (human) response is to ask them to provide all the missing information that will help us to help them better and faster. Anyone who’s ever been the recipient of tech support requests via email will know what we’re talking about.

What’s the solution?

Education. Helping our clients to help us to help them, by letting them know what a great software bug report looks like.

But we can’t expect clients to remember this all the time, to keep a bug report checklist pinned to their monitors.

So this is what we’ve done: each time a new support request is received by email, the auto-response received by the sender contains a brief list of what makes a great software bug report. Sure, it might be too late for the support request they’ve just made.  But we reckon that, over time, this information can only produce better and better results – for everyone.

And what does this checklist look like? Here it is:

  1. Does you website appear to be down (offline)? Is so, use this excellent tool to see if it’s down for the rest of the world, or just you:
  2. A screenshot is worth 1,000 words.
  3. Impact? Is this a mission critical showstopper, or more of an annoyance?
  4. When was the issue first spotted, approximately?
  5. If you’re seeing an error message, please tell us exactly what it says (if the screenshot doesn’t).
  6. Steps to reproduce the issue? If someone else reported this to you, can you reproduce yourself? If we (Itomic) can’t reproduce it, then the issue is *probably* localised to a single PC or your local area network, and you may need to contact your local PC/network support person for additional support.
  7. Is the issue intermittent or permanent?
  8. URL (website address) where the problem is occurring?
  9. Do you have to be logged-in to see the issue? If so, which account are you logged in as (typically an email address)?
  10. Can you think of anything that’s happened recently to your site that might have triggered this issue? Major content edits? Users being added/deleted? New add-ons installed?

Suggestions for improvement always welcome!

Ross Ross Gerring