The art of writing an effective bug ticket: bug reporting

A bug reporter defending his work from a swarm of bugs: this is what makes a good bug report.

Bug reporting is QA’s most valuable skill

For every device you own that has kept working years past the end of its warranty, and for every app that never shuts down at random, you can thank a Quality Assurance (QA) analyst. Their job is a neverending fight not to be noticed by the end user.

In software, QA does this by identifying bugs. This is similar to testing for manufacturer defects when you produce physical goods. The QA analyst identifies when an application does not perform as expected, then reports that bug to the development team. A QA hangs their hat at the end of the day knowing they have successfully prevented a bug, or quickly fixed one before it could affect more end users of the product.

Successful and quick bug fixes depend on the quality of the bug report that is submitted. That’s why it’s important that everyone on the team knows what makes a good bug report and helps enforce the quality standard for bug reports coming from QA.

The art of communication in bug reports

While you might not expect it, what makes a good bug report lies in the art of communication. The bug ticket is a message from a sender to a receiver — the QA to the development team member.

Miscommunication starts wars, ends careers and, in our industry, wastes valuable time and money. Messages are easily misunderstood, especially in the technical landscape of software development. QA has a very difficult job of ensuring the issue they are describing will be easily understood by the development team. Being unclear in a bug ticket could result in a costly project delay or bugs remaining unresolved.

When should bug reporting happen and who’s involved?

Bugs may be found at any stage during the software development lifecycle (SDLC). They should be reported immediately because the earlier they are found the cheaper it is to fix them. The time it takes to fix an issue usually increases exponentially as the software moves forward in the SDLC.

QA & development teams

Once a bug is reported, QA informs the development team that the bug ticket has been submitted. Ideally, an automated Jira command would message the team members instantly when a new ticket is created.¹

Project manager and client

If the bug is highly complex, a project manager will get involved to ensure proper steps and assignments are being taken. Additionally, the client is usually involved if any bugs are found after the software is released into production.

What makes a good bug report — or a bad one — and why it matters

7 Things to remember for making a good bug report

When writing bug tickets, remember that the sole audience is the developer who will be implementing the fix. Reports must be concise and exceptionally clear about what is going wrong and what the expected end result is. All important details should be put on the table to ensure the developer can diagnose, fix and retest in the right timeframe.

In practice, the bug ticket is like a recipe. Miss one ingredient and the dish won't turn out as expected. So here is our recipe for a strong bug ticket:

1.   Reporter & assignee
List the name of the individual reporting the bug. If the defect is raised on the current ticket being tested, QA can assign it to the same developer who worked on the original ticket. If a new issue is raised that is not related to any current ticket, the assignee field can be left for a project manager to find the right developer.

2.    Title & description
Write a specific title relevant to the nature of the issue. This is the first thing a developer sees, even before opening the ticket and reading the details. The description should be a short summary of what the problem is. It is usually one to three sentences long. It should state exactly what is happening.

3. Steps to reproduce
Clearly describe the steps that need to be taken to witness this bug happen in real time. Steps should be thorough and easy to follow. Do not assume or skip any reproducing steps. For complex issues or bugs that are not reproducible all the time, it is best to meet one on one with a developer and discuss the issue further.

4. Actual behavior vs. expected behavior
Detail the actual behavior — what happens after the reproduction steps have been executed. Include screenshots, URLs and any other supporting information. Then specify the expected behavior — how the system should behave in real time. It is necessary to outline what the user should expect.

5. Severity & priority
Evaluate and describe the severity of the bug's impact on the tested system: critical, major, minor or trivial. Priority indicates the urgency of the reported bug — how critical it is for the business. High, medium or low priority assignment determines the order that bugs will be worked on after they are reported. If there are many bugs in the backlog, a bug triage meeting should be held that includes the product owner or project manager to review the severity and priority assigned.

6. Environment & devices:
List the environments where the bug was detected to ensure the developer can replicate it. This is because the application may behave differently in different test, user acceptance testing (UAT) or production environments. It is equally important to define the type of platforms and devices used: URLs, mobile devices and the operating system.

7. Affects version:
List the application version where the issue was detected. For example, you found a bug in your software that affects versions 1, 2 and 3 of your software. You should put 1, 2 and 3 for the “Affects versions” field. This allows the development team to track bugs or defects in already released code, and trace back to where the bug originated.

Are you a yardstick of quality?

Throughout the SDLC, QA analysts have a big impact on the excellence and quality of software that gets produced. Not everyone knows what makes a good bug report and how to write an effective one — but we hope you do now.

You should always review your bug report before hitting send. Read all the sentences and steps in the report. See if there is any ambiguity in the language you used that could be misunderstood. The problem should be reported immediately and reproduced at least three times before a ticket is created.

Bug reports can often be the single line of communication between QA and developer for a particular issue. When QA is accountable for knowing what makes a good bug report, it not only saves the company’s resources, it also creates greater team productivity and the ability to deliver higher-quality products to the end client.

Measuring success in your bug reporting

Knowing what makes a good bug report is a science, writing one is an art.  Following a template structure such as our above recipe for the perfect bug ticket will ensure your reports hit the mark every time. You’ll see results that you can measure in several ways.

Faster Bug Fixes - Your team will notice effective bug reporting as issues get fixed, re-tested, and closed in less time and with increased velocity.

Fewer Bugs Overall - This will also reduce the number of bugs found in future releases as a consequence of the team working on a more stable codebase.

Less Development Time Overall - It will also minimize the time spent on refactoring and architecture improvements. Additionally, the risk of a particular bug resurfacing will be dramatically reduced. 

The end result will be continuous, successful releases and the creation of a remarkable experience for every single end-user.  This is the ultimate measure of success.