How to submit the world's most perfect bug report

Updated Oct 12 2015
findyourafterglow
Pony image by RainbowPlasma remixed by CC license.
Pony image by RainbowPlasma remixed by CC license.

I am not a web developer, but I've spent over a decade working with web developers. In that time, I have been taught the most magical method of submitting tech support requests that make it easy for developers (or anyone!) to understand what the problem is, so that they can hopefully fix it.

I'm slowly training my staff to use this method, and while it takes some getting used to… it's a game changer. Yes, it's helpful when you're trying to tell someone what's busted on a website, but it's also helpful when calling your ISP, or your cable provider, or the person who made your computer. It's basically the best way ever to get help from someone. Here's the template:

1. What I did

Write out the step-by-step process of exactly what you did when something went wrong. Include links to the exact pages you were on, and go into as much detail as possible. Don't just say "I tried to upload a picture and it didn't work," instead say something like:

Here's what I did
Using Safari on my iPhone:

  1. I went to the Dashboard at http://abc.com/dashboard
  2. I clicked "upload"
  3. When the upload window opened, I clicked "select file"
  4. I selected ponypicture.jpg from my desktop
  5. I clicked "submit"

Include every relevant detail you can — what device, operating system, and browser are just for starters. Then say exactly what steps you took, exactly what you clicked, and in exactly what order. The goal here is that someone else could reproduce the exact steps you took, to hopefully have the exact same problem. (So that they can fix it!)

2. What I expected to happen

This is key! Sometimes a broken thing is really just a misunderstanding — you expect one thing to happen, but the tool has been designed for something else. But even when a broken thing really is busted, it's helpful to remind the person you're reporting it to what you're even talking about. They might be supporting tons of tools that work in lots of different ways. Remind them what this particular tool is, and what you think it's supposed to do. So for instance

What I expected to happen

After I click submit, I expect the page to refresh, and to see my uploaded pony picture appear in the gallery.

3. What actually happened

This is where you get to say what's broken. Avoid saying things like "It didn't work" or "It died" or "But nothing happened." Details are your best friends here! Say exactly what things didn't work, and exactly what "didn't work" means… when you clicked a button, did nothing happen at all? Did the page refresh, but not do what it was supposed to? Did something happen, but it was a totally weird and random thing? Details details details.

What happened instead

After I clicked submit, the page refreshed as expected… but then instead of my pony picture in the gallery, I see a photo of a hippopotamus!

Bonus points

For extra credit, be sure to include:

  • Screenshots! I love awesomescreenshots.com's Chrome extension for taking screenshots that you can then easily share via email — they host the image, and you just send a link!
  • Troubleshooting you may have done. (I tried uploading a kitten photo, and THAT worked fine.)
  • Theories you might have about what happened or what's causing the issue. (Because hey! Sometimes you have theories! They might not be right, but might as well include them.)

I 100% walk the talk on this one. Here's an Offbeat Bride Tribe bug I recently filed with my developer:
tribe bug report

She loved it and was able to reproduce the issue and fix it quickly. *thumps chest* YESSSS!

Part of what I love about this style of tech support request is that it focuses on details AND expectations, with the goal being making sure that the person receiving it can reproduce what you did, understand what you wanted to happen, and easily see what's busted. Sometimes, you might hear back that the thing you expected to happen was never going to happen at all — but even then it's great feedback, because it might mean that something's confusing in the user experience… and if you're confused, someone else probably is too!

I'd love to hear from the nerds on this one — any improvements you'd make?

  1. Other useful information to include:

    What type of device you're on. Shit can break on mobile that isn't broken on desktop, and vice versa.

    What browser, and what browser version you're using. Please stop using Internet Explorer for anything.

    <3

    • OH JEEZ. How could I leave out that part? The most important things!! Editing post now…

  2. Oh man, THIS. Part of my job is troubleshooting and it makes me CRAZY when someone sends an email just "can't get to (what I wanted)" or "(link) doesn't work." One thing that's helpful for me (that may not always be relevant for everyone) is whether the issue is happening for other users. We hardly ever know if it's an isolated incident or happening for a lot of people, which makes it hard to prioritize.

  3. Yay!! I work in IT, this is a great start. Most of what you list falls under what we call "repro steps", or the steps to reproduce the problem. We usually give environmental information its own section, as depending on the situation this can be extensive (especially when there are lots of different pieces of software involved).
    The only thing I can think of that I would really want to see that you don't have listed is has it ever worked? Follow-up questions include if so, when did it stop and what has changed since then?
    Let me just say again, this is awesome! Your IT people will love you!

    • Oooh, "did it ever work, and when did it stop?" is such great information to include. Thanks for this!

  4. I gotta say that you ladies are pretty amazing with trouble-shooting.

    I noticed a tiny bug this morning (meaning I got up in Australia, wanted to read comments with breakfast, found a broken link, reported and went about my day) and Megan jumped on it immediately. And when I say tiny, I mean tiny. The Offbeat team is awesome, and I love, love, love that you are so responsive. x

  5. YES! THIS! SO THIS!
    I'm sending this to a dozen people at work in the morning, and that's not exaggerating. Maybe two dozen.

    • I just used this tool to submit a bug to my developer, and she was sooooo freaking stoked.

      • Ariel, can I use this post as a basis for structuring and explaining a possible upgrade to an internal bugtracker? Full credit to you & the Offbeat Empire will be included. <3

Comments are closed.