How to submit the world’s most perfect bug report

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:

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?