1 Comment

Writing Good Bug Reports

By Nadine Parmelee, Senior Quality Assurance Engineer

Nadine ParmeleeThroughout the different stages of the software lifecycle, bugs – or defects if you prefer – are written by many different people who have many different perspectives. Some of these bugs will bounce around between different individuals on a project team quite a few times while others will be processed quickly with little fuss. The defects that are most likely to cause the most activity usually exist because of unclear requirements or because of poorly written defect write-ups. The goal of a good bug report is to allow a developer to reproduce the problem. In this post, we’ll discuss poorly written bug write-ups and how we can make bugs into more effective tools.

Without clear requirements, people often make incorrect assumptions about what should happen in the project. In the same way, poorly written bug reports lead to assumptions about what and where the issue lies, and the project team wastes unnecessary time and money determining the real source of the problem. We’ve all seen these poorly written bug write-ups, some as vague as “feature x crashed” and others that are a convoluted mess of multiple issues. It’s not just developers who suffer when bug reports are written poorly; testers who have to test a “fixed” bug when there isn’t enough information will be left to guess whether the issue is truly fixed, often resulting in a back-and-forth between QA and Development. These multiple-issue bug reports can also throw off statistics for future estimates of testing or regression times. So, everyone on the project team benefits when the bug writer takes a little extra time to make sure the bug details are as clear and succinct as possible.

The basic elements of a good bug write-up are:

  • Short descriptive summary
    Good – “Cancelling from Change Password dialog caused application crash”
    Bad – “Application crashed”
  • Clearly stating where the problem occurs
    If there are multiple areas where something can be done, be clear about which places the problem happens and which places the problem does NOT happen.
  • Easily repeatable steps
  • Clear actual results
  • Clear expected results
  • Keeping each write-up about a single specific issue
  • Including all details pertinent to reproducing the bug
    Specific browser being used if the issue is browser dependent, data points needed, user roles, etc.
  • Excluding details that confuse the issue
    While you may have gone to 15 other dialogs before the issue was encountered, keep the information to just the steps needed to reproduce the issue.

For all of us who write up bugs, it’s in our own best interest (as well as the interest of the development team that needs to get them fixed), to make sure we write them up well the first time so we don’t waste our own time resubmitting clarifications or steps that could easily have been there in the beginning. The product will be better, and that makes for delighted clients.  Take a few extra moments to review your own write-up at the beginning to save everyone time later in the project.