Bug Reporting—Writing for an Audience

People in at least three different roles may be reading your bug report, and the information each group needs is different. I’ll show you how to organize your report so it provides everything your audience will need.

When writing anything, it is important to consider the audience you are writing for. Various stakeholders will be reading the bug report, and each will require different levels of information. Bug reports should be written to help all stakeholders find the information they need so the correct decision can be made about if and how the bug should be fixed.

In this article, we’re going to look at who often reads bug reports and what information they require. We’ll then go on to review what information should be included in a bug report, and how it should be laid out, so that all stakeholders can find the information they require.

Who Reads Bug Reports?

Generally there will be three main stakeholders who read bug reports:

1. The person reviewing the bug
2. The person fixing the bug
3. The person testing the bug fix

The person reviewing the bug could be a project manager, business analyst or someone who understands the needs of the business and the customer best. They decide if the bug is indeed a bug, if it needs to be fixed and when it should be fixed.

A low-severity bug might be recognized as needing to be fixed, but not needing to be fixed immediately. This bug will likely be added to a backlog and eventually picked up by a developer to be fixed. A high-severity bug is likely to be flagged as needing to be fixed immediately. It’ll be added to the top of the list of work that needs to be completed.

The person reviewing the bug will not need as much information as the person who fixes or tests the bug fix. Some of the more detailed information, like steps to reproduce it, are not always required when reviewing the bug. Occasionally, they may look at the additional information for further context, but a brief description is usually enough for them to decide if the bug needs fixing or not. To help those reviewing bugs do so quickly, the bug report should start with a brief description that helps them understand the bug.

The people who fix and retest the bug need more detailed information like the steps to reproduce it and test environment information. This information is essential for debugging and fully understanding the nature of the bug.

The layout of the report should be so that the information required by everyone—the summary describing the bug—is at the start, and additional information is at the end. Doing so will make reviewing the bug as easy as possible and will help the reviewers make the correct decision regarding if and when the bug should be fixed.

Layout and Sections To Include in the Report

Those who read a bug report should dictate what information is included in it. Unfortunately, they are not always aware of what information they need, so asking them is not always helpful. One way around this is to take note of any follow-up questions that arise after the stakeholders have read the report. This is a great indicator of what information is missing and is always worth including in future reports.

It is likely that the format and layout of the report will improve in time. However, here are some helpful sections to help you get started.

Title

It seems so obvious. Everything needs a title. A brief word or phrase so you know what it is you’re about to read. The title isn’t just a heading of a document—it is also what appears in lists of bugs. At the start of a bug review session, stakeholders will be greeted with a long list of bug titles. It can often be the case that this is all they look at before deciding which bugs to review.

Many make the mistake of just including a brief description of the bug in the title. Imagine looking at a list of bugs with vague details in it:

• Button doesn’t work
• Format of page is incorrect
• Unable to edit a record

These examples lack detail and context. The title should provide enough information to let stakeholders know what they are looking at before they’ve read it. You should include details about the feature or application being tested, precise elements that are causing the issue and a brief description of what those elements are (or are not) doing.

Since the titles can’t be too long and are often limited in length, providing enough detail is a challenge. Creating a format that all titles must follow can act as a useful guide for what useful information can be provided.

This is an example of a title format that could be used:

[Feature/Application]—[Impacted element] [Is/is not] [Behavior]

Example:
Calculator—Equals button is not performing the calculation

Using this format will also make the bug lists easier to organize. Bug lists are normally organized by severity and then alphabetical order. Naming the impacted feature and placing it at the start of the title will allow bugs that impact the same feature to be grouped together.

Introduction

Every bug report should start with an introduction. This is essentially an extension of the title, adding some clarity to the bug. The introduction should only include two or three sentences describing the issue. Too much information, and stakeholders will struggle to understand and review the issue.

When initially reviewing the bug, stakeholders will rarely look past the title and introduction. If there is a long list of bugs, they might not be spending more than a couple of minutes making a decision about whether to accept or reject the bug. We want them to make the right decision, so we should be making that decision as easy as possible. A shorter introduction will be easier to understand and review. Too much information, and there is a risk of confusion and misunderstanding.

So what information should be included in the introduction?

First, we need a description of the bug. This must include both the current behavior and the expected behavior. If you just include the current behavior, stakeholders could turn around and say, “Isn’t this supposed to happen?” Providing the expected behavior will add some additional clarity to the nature of the bug. It will also remove any ambiguity later on regarding what needs to be done to fix the bug.

Additional information that can be useful to stakeholders can include details about who this bug will impact and what impact this bug could have. This will help stakeholders understand the severity of the bug. It might be a case that they accept that this bug should be fixed—however, when the bug needs to be fixed will be a different story. The bug might need to be fixed immediately, or it could be fixed at a later date.

An example of an introduction could be:

On the calculator, pressing the equals button fails to perform the calculation that has been entered. I’d expect the answer to the calculation entered to appear on the monitor once the equals button has been clicked. This can result in customers being unable to use the calculator to perform essential calculations, which is its major operation.

Any extra information beyond this should be added to other sections of the document for the stakeholders to read if they require that information.

Severity/Likelihood/Priority

It is not up to the person reporting the bug to decide if and when the bug should be fixed. This decision will be made by the stakeholders reviewing the bug. However, they will rely heavily on the information and advice provided in the bug report.

A quantified number that details how severe they believe the bug to be is a simple and effective way of providing this information. It also provides stakeholders an idea of which bugs should be reviewed first. It is important not to overestimate the severity of a bug. Too many critical bugs in a list can result in a delay in the most severe bugs being reviewed. If all bugs are high priority, then none are.

Steps To Reproduce

When it comes to fixing the bug, the steps to reproduce it will often be the most essential information. The developers fixing the bug and the tester who is involved in retesting the bug (this won’t always be the person who initially reported the bug) need to know precisely how this bug is replicated so they can be certain that the correct fix has been achieved.

This piece of information should appear after the introduction. The reason for this is that not all stakeholders who read the bug report will need to know the steps to reproduce. For stakeholders who merely want to review the ticket and decide whether to approve or reject the ticket, then this information will not always be required.

Steps to reproduce only need to be a list of instructions on how to reproduce the issue. No matter how simple or obvious the bug may be, these details should be included so we’re certain that everyone understands the nature of the bug. You also want to include what you believe the expected behavior should be and example input and output values for additional clarity.

Here is an example list of steps to reproduce.

1. Switch on the calculator.
2. Press a number key (for example, 3).
3. Press an arithmetical operations key (for example, +).
4. Press another number key (for example, 8).
5. Press the equals key.
   • The answer to the entered equation does not appear on the monitor.
   • I’d expect to see the sum of the equation.
   • With the example output values provided, I’d expect to see the number 11.

Additional Information

There may be additional details that can help developers understand and fix the issue. This could include:

• Version of the application that the bug was found on
• Environment that the bug was found on
• Device or PC information
• Browser type and version
• User type

If there is an issue with replicating the bug, then this information can prove vital as it can help developers identify the precise cause of the issue.

Wrap-up

When deciding the format of your bug report, it is essential that you consider your audience. Including all these bits of information in the appropriate hierarchy will ensure that each of your audiences will have what they need to do their job and that the application is on its way to perfection.

It is likely that the layout and format of your bug report will change over time. Finding out what information each of your audience requires can be a challenge. The simplest way is to ask them—however, sometimes they don’t always know themselves. Alternatively you can take note of the questions they ask or comments and changes they make to the report itself. This can contain hidden information that can help you improve your report.