I have always been a strong advocate for the summary being considered the most important part of a bug ticket. Sometimes I get funny looks when I mention this but more often than not I get the understanding nod, especially when I am talking to software testing or development veterans. But for those of you who might not be sold on that position let me present my case for the summary as not only the most important part of a bug but what needs to be included in a summary to make it so useful that it is the most important part of the bug.

PRACTICALITY


In my opinion there are two things that make the bug summary so important. The first being the reality that development teams have limited time. The second being that a bug summary can be a useful tool for project leads.

Limited Time
Developers are always pressed for time. Every project has a running clock that is constantly talked about in almost every meeting. The all-important launch date. Whether it be the project’s beta release, initial launch, patch release or small content release, there is always a deadline of some sort that development teams are working towards. This deadline is almost always sooner than they would like. Therefore, the longer they have to spend deducing the actual issue with each bug written, the less time they have for other important tasks.

Due to the limited time available developers tend to refine their ability to quickly scan and prioritize a list of issues in a database. They do this almost entirely based off of the bug summary. In many cases developers won’t even open a bugs ticket before starting to work on it or deciding whether to spend any time addressing the issue or not. So unless you grab the developer’s attention immediately and clearly, chances are they have already moved on to the next in a long list of bug tickets vying for their attention.

High Level Meetings
Another thing to consider is that programmers, artists and designers are not the only ones who make use of bug summaries. Frequently a project manager, producer or other team lead has to discuss the current state of the project, often times listing key issues they are experiencing that may impact the projects critical dates. Sometimes the issues they are discussing are bugs that have been uncovered during the testing process, especially towards the end of a project.

Therefore, a well written summary is exactly the type of material that these presenters need when explaining to people outside of a project the challenges they are facing. In essence, it is a big help to them if a bug summary is so perfect that they can read it and everyone they are presenting to immediately understands how the issue impacts a project. Conversely having to try and deduce what is important in a bug’s ticket and how to present it makes it far more difficult for the presenter. Remember, people like problem solvers. Not problem creators.

THE HOLY TRINITY


There are three things that at a minimum every bug summary should include if you want to increase your chances of an issue being addressed by the development team. These three things are Defect, Trigger and Location… the Holy Trinity.

The Holy Trinity

Defect
This is the actual issue. Is it a crash? Is it a graphical error? What exactly is the issue? And let me be clear. It has to be an actual issue. Frequently, you will see bug tickets written in such a way that they are merely describing what is happening in an app. In essence you end up with the bug summary being a statement not a bug. For instance –

The user is taken to the Wild Woods when completing the Victorious Weasel quest in Sandy Brook.

Seems good right? Unfortunately, it is a statement of what is happening and doesn’t actually state what the defect is. It relies on the reader knowing what quests link to what areas. On large projects or projects that are in flux, this information may not be known by everyone that may be reviewing a bug ticket. In fact sometimes people who are not involved with the project day to day are reviewing bug tickets. So a safer way to word this issue is –

The user is incorrectly taken to the Wild Woods instead of the Enchanted Forest when completing the Victorious Weasel quest in Sandy Brook.

Now you have an actual defect being listed right up front. The word “incorrect” immediately provokes a response from the reader that there is indeed an issue and then follows it up with what that issue actually is. In effect clearly stating the defect right away.

Trigger
The next of the big three is the trigger. What causes the bug to occur? Did the user press a button? Was a specific choice made during a dialog tree? What triggered the issue? Often times this is something obvious like a button press. Sometimes though the user wasn’t taking any action and it is more of a situation where it is an “at a certain point” type of deal. For example –

The Food Choices video freezes during playback when the Food Choices video reaches 3:48 from the Unlocked Videos section.

Location
Where does the defect occur? Not when, but where. Does it occur on the options screen? Does it occur on the events listing page? Or does it occur in the all too pervasive lava level? This is especially important since most of an app’s functionality is used in various locations throughout an app. So narrowing down an issue’s specific location may be critical for the development team to deduce what is the actual cause.

Different things happen in different areas, so one piece of functionality that works everywhere else narrows down what the programmer is looking into as they can deduce what is different in that area from other areas that the code is triggered.

Presentation Order
At Digital Dream Forge we like to hit the reader immediately with the defect then move to the trigger and finish it off with the location. This is our default bug summary style. It quickly grabs the readers attention and then follows it up with the important information. This is not the only way of presenting those three key components though and many clients prefer things presented in a different order.

For example, we sometimes get requests to include the location first and then the defect and trigger. This typically has to do with the way their bug tracking system works or just personal preference by the development team. This is perfectly fine. All three components are still being covered and if it helps the development team then it is a good request. Remember that bug summaries aren’t written for software testers. They are written for development teams. So whatever makes it useful for them is the best way to format it.

CONCLUSION


While other parts of a bug ticket are important, it is the bug summary that bears the weight of quickly and efficiently grabbing a developer’s attention. Plus, it is useful to the widest group of readers. Crash logs and detailed steps are nice but ultimately not as frequently referenced or easily presented to other individuals. If your bug summary contains the Holy Trinity and is well written, you will start to see the advantages to a project in terms of usefulness and efficiency.

Jeremy S. Barnes