Regardless of project planning and preparation, bugs find their way into the code. This is an inevitability, and it’s why QA exists in the first place.

Fixing these bugs can be a very difficult process for a number of reasons, including the volume of the issues, their complexity, and more. But the pain of correcting such issues can be reduced by improving the quality of issue reports.

While often overlooked, this is a simple step that can have a huge impact on both the efficiency and quality of a team’s work and ultimately the application being tested.

The Core Benefits of Improving Issue Reports

The better your issue reports are, the more effectively every member of your team can do their job. Product owners can better triage issues; project managers can quickly and properly assign issues; developers can more effectively resolve issues as they are more understandable, and quality assurance can better verify issues.

High-quality issue reports also offer a number of ancillary benefits, including:

• Fewer duplicate tickets reported, less developing, and less testing
• Reducing cycles because issues will be resolved the first time
• Better communication between developers and quality assurance teams
• Insight and control better maintained by POs and PMs
• Fewer surprises, which means a smoother project

How to Improve Issue Report Quality

1. Be clear and concise

Cut out the fluff. Don’t write lengthy prose and don’t include unrelated information. Clearly and concisely describe the issue.

2. One issue, one ticket

Each issue report should have one issue listed on one ticket.  Issues need to be individually triaged, assigned, resolved, and verified – and because of that, they need to be individually tracked.

3. Include the most important components

In order for issues to be tracked correctly, issue reports must include steps to reproduce, actual results, and expected results. We’ll go over each in turn.

Steps to Reproduce:

Without the properly laid out steps to reproduce, the issue is not worth logging. To be fixable, people need to be able to understand how the issue is found. Issues like “sometimes the app is slow”, “loading takes too long”, or “crashes often” don’t have any value.  Repetitive steps can be condensed as the project progresses. Here are a few examples:

Actual Results:

This is a short section where you describe the issue itself. In most cases, the results section should be accompanied by crash logs, screenshots, and/or videos. For example:

Expected Results:

Including the expected results may be the most important component of a proper issue ticket, yet it is often overlooked in the issue logging process. The purpose of expected results is to lay out how the issue could be fixed. If these are not indicated, the issue may be resolved but in a different way than desired, which in itself can result in more issues.

Expected results are used by each team member:

• Product owners make sure the issues are valid and modify the tickets as necessary
• Project managers assign the issues to the developers who can best implement the fix
• Developers completely understand their goals before starting to resolve the issues
• Quality assurance verifies that the steps to reproduce now lead to the expected results and the issues have been properly resolved

Who Should Care About Issue Reporting Quality?

The majority of issues will be logged by your quality assurance team, but issue reporting quality is important for everybody involved in the project. Product managers, product owners, and especially developers need to be able to identify and write proper issue reports and understand their benefits. If key components are missing, the ticket should be sent back with a request for the reporter to provide the missing details. The quality of issue reports impacts everybody working on a project – the better they are, the more smoothly the project will run.

Examples of Good and Bad Issue Reporting

Below is a chart comparing poorly logged issues to properly logged issues. The first issue does not have enough information to be valuable, the second has too much information including some that should be split into multiple tickets, and the third has all the right details but is written in a way that is difficult to understand. Note the formatting of the issue reports – laying them out correctly doesn’t take much time, yet makes a big difference.

To summarize, ensuring that issues are reported properly can significantly impact the success of a project. Issue reporting affects all team members: product owners, project managers, quality assurance, and developers. Taking the time to log issues correctly using the above best practices will improve all facets of your project.