I love it when you find bugs

Mon 17 May
2010

Posted at 3:59 PM by Max Cameron in Tech Start-Up 101

Writing good bug descriptions isn't easy, and developers love to bitch about bogus bug reports. But really, it's our job to help people report them better. How's a civilian supposed to know that sometimes we think in lists, and not in stories? We work with a distributed team, so they can't just sit down next to us and walk through it. When they find bugs, it's our job to hunt them down and squash them with impunity. I wrote this letter to our team-members to help me reproduce bugs without lengthy skype conversations or tons of email. This isn't for customer consumption, but rather for our internal team. I figure we owe it to them to help them write better bug descriptions.

Hi everyone,

Disclaimer: This message was not written with anyone in mind. I tagged everyone who frequently helps me with bugs, and I think it will help everyone.

Ok, on with the show.

I love it when you find bugs.

Finding and squashing bugs makes our product better. Even though it sucks when something doesn’t work the way you expect it to, it’s far better for us to find bugs than for our customers to find them. When you report a bug, my job is to make it happen on my computer. When I can do that, I can stop our developers, reproduce the problem, and get them working on a fix. When I can’t do that, I get frustrated because I can’t help you even though I really want to. The key to fixing bugs is for me to reproduce the problem. I was hoping I could ask you for a favour in helping me do that. I’d like to set up a consistent and simple way to describe bug-like-behaviour. And I think we can do it without using crappy bug reporting software with hundreds of drop-down menus.

Example time. Everyone loves examples!

Let’s say I try and add a user and it doesn’t work. One way to write a bug report is to tell a story. “Hi Max, I logged into the application and opened up the account manager and I added a user but the little spinny circle kept on spinning and nothing happened. So I opened up a different tab and logged in again and added another user and the same thing happened, but then I switched over to the content manager and came back, clicked a few different users, then I clicked on the first user and there she was!”

Umm ok. Let me get back to you.

Pretty simple bug, not so simple for me to reproduce. I know I have an issue with browser tabs, I know I have an issue with a spinny circle, and I think that if I select a few different users something might happen. But there’s so much I don’t know. So many steps missing, so much context absent. I’ll probably be sitting around hoping that I’ll stumble across the problem. I might call you and ask you to walk me through it (spending more of our time). More likely though, I’ll just try and “figure it out,” face-palming because I can’t help you get the software you need.

And this is just a simple bug, never mind the really juicy, complicated ones.

Here’s an alternate way to log the bug.

A list! Everyone loves a list!

"Dear Max, I found a problem. Here’s the steps I took to reproduce it."

Log into xxxxx.woople.com
Select account manager
Click add user button
Enter user’s name, press tab.
Enter user’s email address
Add user’s password
Click add user
The Spinny circle spins for thirty seconds or more!
While spinny circle spins, I open a new tab on my browser
Log out and log in to the same woople account again
Select account manager, add a new user, and the spinny thing happens again
Close the second tab
I go back to the first site and refresh the page
Go back to user list, still no user
Click add user
Enter user details again. Still no luck
Select Content Manager
Select Account Manager
User appears on the list

Ahhhhhh, lightbulb.

So using this list, I can do a few things:

First of all, I can retrace your footsteps step-by-step, and hopefully, come to the same result that you did (no user in the list).
Second, I can identify a step you took that might give me a hint as to where the problem is (selecting content manager and coming back).
Third, I identify problem steps that we might want to avoid in the future (multiple tabs logged into the same account).
Notice how I used a list to extoll the virtues of a list.

And the best part is, when something weird happens, you can start a list, and go step by step through the process and describe everything you click and everything that happens as you do it. You won’t have to worry about writing a story from your memory twenty minutes after you see the bug.

Thanks for taking the time to read this message. I mean this when I say it: I appreciate every bug you find, and all the time it takes for you to describe them to me. I know how much work it takes (trust me I spend most of my waking hours doing this on our staging environment). It’s tough, detailed, confusing work that makes you focus your mind like a college exam. It’s not fun. But it’s how we make our living, and it’s worth every mind-numbing second. Because when we squash a nasty bug that was hard to reproduce, and savour the moment of knowing it will never, ever come back to haunt us, it makes all those lists and all those steps worthwhile.

With undying admiration,

Yours truly,

Max Cameron, The Bug Hunter

Want to leave a comment? Join the conversation (and vote this article up) on hacker news.