Proper Bugwriting

The software quality assurance process is, at its heart, all about finding bugs in computer code. After a bug is found, it is reported – bug reports are the most visible (and arguably most important) product of the QA process. The purpose of bug reporting, of course, is to provide a clear and concise explanation for where and why something is not working so that developers can quickly replicate, isolate and fix the underlying problem.

Anyone familiar with software development will have seen a myriad of bug reports, often varying in content and quality from multiple-paragraph ‘information overload’ to single, partial sentences with no structure and only vague meaning. Obviously, these are both examples of poor bug reporting that either put in so much information that the critical pieces are obscured or are so lacking in details that they are close to meaningless. Over the years, we here at Beta Breakers have found that a good, comprehensible, bug report consists mainly of four straightforward components:

A short synopsis that accurately describes the issue being reported

This is always the first part of a bug to be read (and often is the only part that is visible in a bug search) and is probably the most difficult piece to write properly, as it needs to convey sufficient meaning in the fewest words possible.

A detailed description of the issues, including any variations for where it occurs or how it manifests

It is important to avoid putting in extraneous details or conflating two (or more) different issues into one bug report here. It is also important to make sure that your description and synopsis match each other; it is not uncommon to ‘think ahead of yourself’ and write up a different issue after composing a synopsis.

Complete steps to recreate the issue

It is important that these steps can be followed not just by developers, but also by project managers, new developers/testers and other stakeholders who may not interact with the application on a daily basis. Avoid the temptation to skip right to the area of the application that is failing. Be sure to include a couple of basic steps to get an unfamiliar user to the correct point to observe the issue in question.

Supporting evidence that illustrates the issue

Screenshots are the most common form of issue illustration, but this can also include things like text excerpts from design documents, PDF attachments, log files or even short videos demonstrating an issue that is difficult to understand without ‘seeing it in motion’. Some bug reports will not require any kind of illustration, so there will be times that this step can be skipped, but as they say, ‘a picture is worth a thousand words’.

Including each of the above components in a bug report will yield consistent, readable and easily-comprehensible issue reports that can be acted upon with minimal need for clarification. Happy testing!