Thursday, March 01, 2001 ..:: Home ::.. Register  Login
   TechTidBits (Blog)  

How to write a GREAT bug report?

Feb 23

Written by:
Saturday, February 23, 2013 4:14 PM  RssIcon

imageDo you write bug reports?  Do you get asked LOTS of questions about your bug reports but can’t understand WHY?  Read on for some tips to write better bug reports.

Do you test programs and write bugs?  Do developers continually pepper you with emails asking questions and you just get annoyed at them?  Do you find yourself really frustrated and asking “why don’t THEY just GET IT?”

Well, this is ONE developer’s perspective to try to help you raise the bar on bug reports you create!

“uuhh Peter, WHY do I need this?  I write GREAT bugs that tell you what happened, what’s the problem?”  Great question!  (aka rephrasing the question, WHY THE HECK DO I NEED TO WASTE MY TIME READING THIS? JUST FIX MY BUGS MAN!”)  In my past of working for software companies, I’ve noticed some patterns and myths, which I would like to help explain and dispel!

What is a bug report?

You ran SMACK! into something that broke on “our” application and you need to communicate it to help make the product better!  Great!  We’re starting off on the right foot!  I worked with a QA manager once who always tried to remind devs we’re ALL trying to make our product better, let’s work together!  I always admired him for this consistency and patience.  Now, let’s continue this.  If you put in the right amount of effort, your bug will get the RIGHT amount of attention.  If you put in the wrong amount, well, it’ll just get pushed off and it’ll waste everyone’s time. 

The thing about bug reports is, when you create them, you usually don’t know just how many people will be looking at it.  At best, two, you and one developer.  Worst, teams, GOBS of people!  From project managers, to architecture developers, marketing people, consultants, DBAs, all before the lowly developer even gets assigned to FIXING the bug!  Then, once it’s fixed, QA needs to PROVE the developer indeed fixed YOUR issue (and not something else they wanted to fix) and then there could be another verification/build engineer who needs to document what was fixed and going into the next build.  All this to say, there could be a few people looking at your bug!

SO, what’s the right amount of effort?  Well, let me start of with what’s the wrong amount.  One sentence with an optional vague and/or ambiguous subject line is not enough.  Yes, I’ve seen one line sentence bugs which lead to weeks worth of effort!  Five pages of minutia detail is also a quick way to get put off until “the next version.”  So finding a happy medium is required.  Here are some tips I’ve come up with to help you write a GREAT bug report!

Raising the bar on raising bugs

CEO Summary

  • One issue = one bug
  • Don’t ask question in bugs
  • Please, please please, leave the emotion at the coffee machine
  • Provide as much as possible for anyone to repro
  • Expected outcomes
  • Severity/Priority

Dev Summary

  • One issue = one bug
    • LUMPING two/three/four/five bugs into one is NEVER, repeat NEVER a good idea.  Ya, sure YOU save time, YOU get your ideas off your chest.  But what you really do is guarantee one of those issues will get forgotten (ie NOT FIXED) and when you get it back, you’ll be frustrated, meanwhile the developer worked three days to get the others fixed, but that effort gets forgotten.
    • Another reason to so this is because it's difficult to balance “bug load between developers when “one bug” (one of those LOADED bugs) has unknown amount of work/time estimates, if you write one bug per issue, then it’s EASY to share these bugs among multiple developers and therefore you’ll get your bugs done faster!  WOW! THAT’S cool!
    • Write one bug, get the bug # and reference that one in the two/three/four others if you need to, if they relate, that’s fair!
  • Don’t ask question in bugs
    • Use email to the proper people for that!  I’ve seen this many times, and believe me, devs HATE this!  If you’re unsure, I’m pretty sure you won’t like the “quick fix” solution/answer the developer is most likely going to give you!
    • If you have a question, I’m sure others will to, but the devs not the right person to be asking, marketing, product manager, CTO, R&D manager, are just some of the suggested people to contact.
  • Please, please please, leave the emotion at the coffee machine
    • Yes, users, people, everyone gets frustrated with “our” apps!  Especially when deadlines are looming overhead!  But everyone’s human.
    • If you want your bugs treated fairly, don’t put bad attitude (BA) in your bug reports, leave the name calling (people, products or features) into the bug report, to quote a movie “Just the facts ma'am.”
    • Be detached when raising a bug, an issue exists, doc it, and it'll get resolved.
    • When negativity is attached to the bug, it sends the wrong message to everyone touching it, yes, even the developers.
  • Provide as much as possible for anyone to repro
    • This is the ONE area where people usually balk!
    • YES, I know this takes time, yes, it’s time consuming!  But remember when I said there are A LOT of people touching your bugs? Do you want everyone of them coming back to you or emailing your or phoning you with questions on what did you mean, how to reproduce, or what the heck are you doing?  Every time?  No, I didn’t think so.  So please save everyone a few moments and document your steps to repro!
      • I worked at one place and one guy coined “Storyboarding” I LOVE that description (I have to note, he HATED that haha), that is EXACTLY what I’m proposing!  You know the cliché, a picture is worth a thousand words!  Never more important than in a bug report!
    • Start from beginning, YES, sometimes it matters, especially when there are multiple ways to get somewhere and each path has it’s ever so slightly different outcomes/visual elements.
    • I’ve seen bug reports that say “I can’t see report XYZ” which lead to one developer looking at security, when in reality it was a problem with the SQL in the RDL which was a completely other group of people!  Steps to repro would have cleared this up from the beginning.
    • Steps to repro also help to clear up your own ambiguities BEFORE the bug is raised/saved/finished.
      • I’ve seen many times while someone is raising a bug they found out it’s doing THAT be design, or it’s on purpose, or they’re doing something wrong, and it’s not actually a bug.
      • Yes, I’ve also seen it where someone found two/three/four NEW bugs while doing this, so this is a double edged sward, ya I see that too.
    • Many people need to have complete scope on issue, one liners are not sufficient to convey what is going on.
      • Pretend an intern is QAing the bug, help them replicate it and give them a way to prove it's fixed (expected results).
    • YES, it's a burden, BUT chances are high you'll expose key pieces of NEW information to completely fix/solve the issue.
    • There are MANY times, where something works on one server but reproduces on another (ie server farms), developers need the right data/steps to concretely reproduce it so they can know when it's sufficiently fixed
    • If you see numbers/primary keys/IDs on the screen, please, please, please add them!
      • I worked on one bug which had a completely different source than what the bug was originally alluding to, I only found the REAL bug after getting the right data to search for!
      • If you don't know what that is, that's fine, just list key pieces of information on the page, especially if you see columns/fields labeled "ID" which are key to your bug.
    • Screenshots/screencaps/pics worth a thousand words
      • For any Windows box, you can use PrtScn button, especially ALT+PrtScn will take JUST the active window
        • If you’re doing PrtScn, don’t copy too much information like personal emails.
      • If you’re using Windows 7 or newer, you should learn to LOVE Snipping Tool image
      • Another popular tool is SnagIt
  • Referencing other bugs is fine, but don't use as a crutch
    • If you added a bug last week week, steps to repro likely WON’T apply, but if you're raising a bunch at once, sure, saves work, cool.
    • Please provide hyperlinks as well as bug #
      • People could be looking at bug reports from home, or work, on the road, on their phone or laptop.  Help them work wherever they are.
  • Expected outcomes
    • Second in importance ONLY to steps to repro.
    • You’re telling me WHAT went wrong, buuuuuuuuuuuuut what were you expecting?  And MOST of the time, no, it’s not self-evident/explanatory, please spoon feed it.
    • This helps the devs/QA KNOW when they’ve nailed the RIGHT bug and not something else you didn’t document.

Now you know to write a GREAT bug report, there are usually one other important fields on the bug report, yes, of course I have some suggestions on those too!


  • Improperly setting severity won't get your bugs resolved sooner
    • Think about Crying Wolf, if ALL YOUR BUGS ARE 911, CRITICAL, VITAL, WORTH THOUSANDS OF DOLLARS IN THE NEXT DEAL (yup, CAPSLOCK on purpose), people start to question your bugs from now on.
    • It could serve to get them put off longer.
    • Here are some suggestions
      • Critical
        • The app crashes
        • Data is corrupted
        • Drastically and very negatively impacts over 75% of user base (I’m just throwing some number out there, entirely up for your own discussions)
      • High
        • Drastically inconveniences users workflow
        • Wrong data is displayed but no harmed in the process, it looks corrupted but isn't really
        • Negatively impacts 50% of users
      • Medium
        • Default severity

Those are my tips on how to write a good bug report, I hope your issues will get get fixed faster and with less reactivations!  Now it’s time to grab a coffee and get coding!

Location: Blogs Parent Separator TechTidBits

2 comment(s) so far...


Re: How to write a GREAT bug report?

re: Please, please please, leave the emotion at the coffee machineI might also add that devs quite often put in an enormous amount of effort into developing features and what might seem like simple functionality from a users persperctive is usually for more complicated than is obvious to a user. "Attitude" in a bug report can be quite insulting.

By Mr. Congeniality on   Monday, February 25, 2013 11:05 AM

Re: How to write a GREAT bug report?

That's a GREAT comment Mr. Congeniality. Yes, I agree, sometimes a simple "oh just put that in" can take DAYS to implement and even more to test!Thank you for stopping by! I hope I can convince to return in the future?! Have a good week!

By Peter Henry on   Monday, February 25, 2013 11:07 AM

Your name:
Gravatar Preview
Your email:
(Optional) Email used only to show Gravatar.
Your website:
Add Comment   Cancel 
Copyright 1999-2012 by   Terms Of Use  Privacy Statement