What Are the Qualities of a Good Bug Entry?

Making a bug report can be a surprisingly subtle process – and precision is everyone’s friend when it comes to bugs.  In this section, we’ll briefly address the most important aspects of bug reporting.  Always remember:  the goal of a bug report is to get a problem fixed.

The process of removing problems and fixing bugs in software (or hardware, for that matter) is a lot like the process of identifying an illness in medicine:

1. Study the symptoms
2. Trace the symptoms to a root cause
3. Once the root cause is found, cure the root cause, or
4. If the root cause is not treatable, find a treatment that eases or removes the symptoms

In the case of software, the identification of the root cause is generally the process of locating a specific set of instructions that either conflicts with another set, or that itself is mal-formed.  The symptoms experienced are generally signposts that point towards this set of instructions, and taking those symptoms and turning it into a map of the problem is how the developer finds the bug in question.

With that said, the bug report is the primary tool you have in helping developers identify bugs in software you’ve used.  There are bad bug reports (“It’s broken.” – that’s not a joke, this author has seen bug reports that read exactly that way), and good ones.  What are the qualities of a good one?

Concise

A good bug report is concise – it is to the point, and spends a minimum of time talking around the problem.  Use clear language, and only enough to describe the issue at hand.

Isolated

Isolation is making sure that any individual bug report refers to only a single bug.  When entering a bug report, always try to make one report per bug, and one bug per report.  When chasing a problem, a developer will have a much easier time locating and repairing a single error – not because he or she can’t deal with more than one thing at a time, but because it’s very likely that any given set of bugs probably exist in different sections of code, or even different files or directories.  If a developer had to look at two different bugs at once, it’s likely that the two would confuse each others’ trails, making it very hard for the developer to dig out either one.

For example, if a “File – Open” dialog throws an error message, that is a different bug than attempting to navigate to a new page and having another error message – even if the messages end up saying the same thing.  These two occurrences are better off being entered into two separate bug reports.

Although multiple reports of the same bug can also be a problem (because the QA staff must verify a bug, and multiple reports potentially use up their time), if you are in doubt as to whether what you are looking at is new or a duplicate, it is better to enter it as a new bug.  If it is later identified as a duplicate, the entry will be closed, but a link will be made in it indicating the bug report that originally identified the problem.

Specific

Specificity is crucial to the technicians trying to find the source of the problem.  This is related to isolation (in that your report should pinpoint a single issue), but is also its own subject – when you describe the bug, be as specific as possible.  For example, if you experience an error when you navigate to a particular screen of an application or website, what is the method by which you navigate to it?  Are you clicking a link from another page, or picking an item from a menu?  Are you pressing a “submit” button and being redirected there?  Are you using a Mac or a PC?  Knowing these details can chop minutes or hours off of the process of finding the source of the problem.

Reproducible

The first thing a QA tester or developer will tell you when asked what makes a good bug entry is this:

Steps to Replicate.

Although often a bug does not evidence reliable behavior, if the reporter can find a method by which they can reproduce the problem consistently, that is vitally important information.  Including that in a bug report can mean the difference between saying “Oh, I see, click!” and spending hours or days in detective work trying to find the error and observe what it is doing.

Steps can be laid out in simple numbered lines, and often this is the best method.  For example:

1. Open [application or site]
2. Open menu X with Alt+X keypress
3. Click on menu item “widget” with mouse
4. When “widget” page/screen is loading, click on banner in upper left
5. Computer will ignite and spark (describe problem behavior here)

Prioritized

If possible, a scale of importance should be applied to the bug.  Having a priority assigned to a bug helps the development team determine which bugs should be addressed first, and which might not be so important to deal with.  Not every bug should be considered a “stop the presses!” matter, just as not every bug can be written off as trivial.

This topic brings into spotlight the nature of individual perspective.  When dealing with software and web development, at least two widely differing perspectives are brought together to work towards a common goal.  Those differing perspectives are the most common causes of friction and strife in teams.

For example, the perspectives of a developer are very different from those of a marketing professional, because the two measure value based on very different elements.  A developer can look at a spelling error on a label and consider it the most trivial of issues, because generally software professionals measure importance as directly proportional to the complexity of a problem – changing the text on a label to correct its spelling is among the simplest operations one can perform.  Meanwhile, the aforementioned marketing professional measures importance by the content and impact of memes (ideas and concepts) – for that person, a spelling error in a highly-visible place will be considered a critical and business-threatening problem.

With this in mind, when creating a bug report, the reporter should assign to the bug a level of importance that the reporter feels is appropriate.  This will place the bug in the queue for resolution at an appropriate level for its importance.  Don’t worry overmuch about being precisely correct – if some question exists about the importance of a bug, the development staff will return to the reporter for clarification.

The Borked Scale was invented in 1998, specifically to help in assessing the criticality of a bug in a way that accommodates the widest number of perspectives.  This scale rates two factors of a bug – its severity, and its visibility.  These are measured on a scale of 1 (lowest) to 5 (highest), and are multiplied to provide a Borked factor.

The scale produces a Borked factor of between 1 and 25, with one being the least severe and rarest of occurrence (for instance, an off-color on a banner that is viewed by perhaps one individual user in a thousand), to the most severe and frequent (a crash that causes the user to lose data entered, which happens to practically every individual using the application or site).  Generally Borked scores of 16 or higher are considered must-fix, and quite often are reasons for emergency patches to be issued, while scores of 4 or less may go unrepaired for the entire lifetime of the application.

Notice the outlying scores that are multiples of 5 are color-coded as critical and must-fix:  this is because of the nature of either their severity or visibility being highest.  Usually this means that either every single user is experiencing the problem, or those who do experience it are having the most disastrous outcome in using the system.

Expected and Actual Behavior

This is the description of what the bug actually is – how it behaves differently from what the user expects to happen.  A short description of what the app does (i.e., “Screen scrolls forever” or “Error message and system locks up”) versus what is expected (“Screen scrolls to entry that matches search result and stops with result 40 pixels from screen top” or “System should never lock up”) is to be given.

Screen Shots or Other Media

Taking an image of the screen along the user journey to the bug can be highly valuable – these help the development staff confirm that they are following the right path to arrive at the bug.  Users on a PC can take an image of the screen by using the “Print Screen” button (on Windows, this takes an image of the entire screen, and places it in the Copy buffer), where it will wait to be pasted into a word doc or image-editing software with a CTRL+V key-press.  Notice this means the entire screen, including all background and running applications.  If there is sensitive information there, you may wish to crop the image a bit before including it in your bug report.

Another alternative is using the key combination ALT+SHIFT+Print Screen – this will capture only the active application in the foreground for the copy buffer.

Contact Information

When reporting a bug, always include contact information (most systems for bug resolution include this information automatically).  In order for any questions to be answered, the development team must be able to get in touch with the individual who first reported the bug to get first-hand information regarding the issue.

Proofreading

Proofing your text is very helpful.  Go back once and re-read your report before submitting it, to make sure it is understandable and intelligible.  If possible, read it out loud to yourself and see if it sounds clear to your ear.

Professionalism

Experiencing a bug in a program or site when you need it to work is a frustrating experience – no one will contest that.  However, as was stressed in the beginning of this writeup, the objective of a bug report is to repair the issue.  A bug report is not a place for abuse or venting.  Chances are the individual(s) reading the report are not responsible for the problem in the first place, and an unprofessional report may be discarded or disregarded – it almost certainly will not have the attention paid to it that it deserves.

Summary

A bug entry relies on professional, accurate and direct language describing the nature of the problem experienced, with as much assistance in locating the error as is possible to provide.  Ultimately, its purpose is to direct development staff to the source of the problem, with a goal of providing the fastest path to repair available.