Top 3 must haves for writing good bugs (er, bug reports)


Top 3 must haves for writing good bugs bug reports

Brian, another tester at Microsoft, and myself were discussing bugs over the lunch the other day. Sad but true, we actually had a good time talking about what makes a good bug report. There are 3 messages you need to send to three different people.

1. Dear PM, I have a compelling title.

“My avatar is beheaded.”

The title is a note to the PM saying what the bug is about. It should be catchy if possible. An interesting bug he pointed out was one where an avatar was being clipped. The title in his example was compelling and clear. It could just as easily have been titled “User controls with custom graphics is clipped.” While technically accurate, it really doesn't convey the situation very well. Spend a little time with your bug titles and think about your audience being your feature PM and maybe the triage team. Funny titles that are relevant and profession are the best.

2. Dear Managers, I have compelling user story.

“Mary is a developer at a 3rd party company. Her goal is to use our API to make a mobile application for her customers. She attempts to get up to speed with the SDK and finds example #2 confusing.”

Two sentences at the top of the repro steps that lets people who don’t have the technical details at their fingertips know who is going to be impacted and how badly. If your bug goes to a "war team" it's going to have a better chance of getting a fair treatment if you write a little story about who is impacted and how. Name the actor and introduce them. Be clear about the actor's goal and be clear about how they are impacted by the bug. Use a team persona if you have them.

3. Dear Developer, I have all the technical details you need to see this bug in action.

“Repro Steps:

·         Install the latest SDK from \\buildshare\build\latest

·         Open the help file CHM

·         Navigate to “Getting Started -> Example 2”

Expect: A complete code sample that new users can plug in to get started.

Result: This example is missing an implicit Serializable class that might be hard for new users to create from scratch.”

Be sure to be very specific about shares, paths, URLs, etc. Your goal should be that any developer or tester on your team can reproduce the bug without having to send you and email or call you to ask about details. Nothing frustrates me faster than trying to reproduce another’s testers bug when they didn’t include the details.

It’s OK to use jargon and assume a level of product knowledge. You should also assume the person who is using the repro steps is smart but very busy. They could scour the intranet looking for the drop share or they could just click the link in the bug. Don’t waste someone else’s time looking for details you already knew.

Remember writing good bugs takes some time

Writing a good bug report usually takes me about 20 minutes. That’s not counting all the time around finding the bug and digging up logs or other supporting evidence. Just finding a bug isn’t enough. You should also do a good job logging it so your customers can get the awesome product they deserve.

 Edit: Thanks Gram for pointing out that devs already write bugs. It's the reports that need work. I look forward to your next brain melting bug.

Skip to main content