Software: December 2009 Archives

No matter what you are using to keep track of defects that you find in your software, there are certain things that you should keep in mind when you are documenting a defect.

1. A CLEAR AND CONCISE SUBJECT LINE / TITLE
   This might be the most important part of creating a good defect report.  With this, the people responsible for fixing the bug/defect and quickly group several similar or identical problems into one investigation.  A good description will have at least 2 elements:  An action taken and a result
   
   EXAMPLES:
   Bad:  The website isn't working.
   Good: Clicking on 'Home' link takes me to a "missing page" error page
   
   
2. CLEAR AND CONCISE STEPS TO REPRODUCE THE ISSUE
   More often than not, a majority of the time it takes to fix a defect or bug occurs in the "trying to reproduce it" phase.  Even if we track you down to have you give us a demo of the problem and that demo only takes 2 minutes, the time it takes to actually catch up with you and get that 2 minute demo stacks up quickly.  So, in the body of your defect, you should give developers more information than you think they could ever use.
   
   EXAMPLES: (We'll continue with the bug started in step 1)
   Bad:  I clicked home and was taken to a blank page.
   Good:
   1. I opened up a browser and navigated to our live site ( http://www.ourdomain.com )
   2. I logged into the site using the "Login" link
   3. I clicked on the "Message Boards" Link
   4. From Message Boards, I opened up the article "Summertime fun spots"
   5. I clicked on the "Add Comment" button
   6. I typed in a comment, but didn't hit [submit]
   7. I clicked on the "Home" button in the menu bar of the site
   8. I saw a blank page that stated the page was not found
   9. In the address bar, there was this URL:  http://joedeveolper.dev.ourdomain.com/home.html
   10. I'm using Firefox for my browser on Windows 7.
3. A RECORD OF REPRODUCTIONS
   There is an old and sometimes joked about adage that states "It's not a problem if was can't reproduce it." While this may seem rather flippant and careless, there's also a huge grain of truth in it.  Sure there may have be an actual problem, but in the terms of prioritization, I'm sure it's easy to see that a defect that is either un-reproducible or difficult to reproduce is less important to fix than something that happens all the time.  Of course, this is an over-simplification as a bug that wipes out all of your data, even if it is almost impossible to reproduce is pretty damn important.
   
   EXAMPLES:
   Bad: I think I heard someone else had this problem
   Good: I was able to reproduce this on Internet Explorer, too.
   Best: I was able to reproduce this on Internet Explorer too.  I also got Sally and Jim to reproduce it on their computers, as well
   
4. SCREENSHOTS OF THE PROBLEM
   If the problem is visual in nature, it's always a good thing to include a screen capture of the problem.
   
   EXAMPLE:
   "The background color for the Name and Description columns do not match on the albums listing page."
   
   
5. ADVANCED TECHNIQUES: Recording a macro to reproduce the problem automatically
   There are many tools out there that will allow you to record all the clicks and typing you do on your computer.  Recording these actions could prove to be very helpful to the people trying to fix your defect.  Even if you list all of your steps as accurately as you believe is possible, there might be something that you do, thinking it's insignificant, that the developer will catch on and realize exactly what the problem is.  Perhaps you clicked on the graphic of a button rather than its, text.  Perhaps you submitted a form by hitting the [Enter] key on your computer rather than clicking the [submit] button on the web page.  Another major benefit of recording your actions is that your recorded actions are now documented, and it might be possible to create an automated test from them.  With an automated test, your defect might be caught next time before it ever gets to a production environment.  Keep in mind, these tools record your actions ( move mouse here, click here, type this ).  It does not record a video of what you see.
   
   SUGGESTED SOFTWARE:
   
   Bad Boy a very nicely done tool that is, unfortunately, a windows and Internet Explorer only tool.
   
   Selenium IDE:  This tool is also a very good program.  It sits on your system as a Firefox Plugin.  So initial recording of a defect will be done in Firefox only, but it can be played back using several different browsers.
   

These techniques and suggestions are not the be all and end all of 'best practices' for reporting a bug or defect, but they will certainly get you further down the road in being a productive partner when it comes to making sure your company produces the highest quality software.