All developers received at some point bad bug reports. There reports that do not say anything (“It’s not working!”). Other reports make no sense or do not give sufficient information or even information that is false! Bugs may result from negligence of development teams (even though it is sometimes difficult to acknowledge it), users’ awkwardness, software interference, hardware problems…

Whether there are many or not, bugs are cumbersome, and that explains why we often consider technical support as a “hellacious” task. However, bug reports are not all unpleasant: some are clear, useful, and informative. With just a little effort, a report’s efficiency is improved. But the question is how to write a good bug report.

Start on sound basis

The goal of a bug report is neither to convey someone’s panic nor to blame someone; its intent is to have the developer see the program crash. One can show it firsthand or provide detailed instructions on the way to reproduce the crash. If the developer is able to have the system crash, he will use data collected during the process to discover the cause of the bug. If he is not able, he will then have to ask for these data which is a waste of time.

A bug report should focus on facts. For instance: “I did this and here’s what happened.” Avoid all speculations (i.e. “I believe that this is the problem…”). It is like when you have a doctor’s appointment, simply describe your symptoms and medical history. Let the doctor do his job! Do not take any medication without the advice of a specialist.

When exchanging with developers, what you wish is for the bug to be corrected rapidly and… correctly. Do not risk to harass developers or to lose their time. Even though they may be responsible for the error, the bug, as well as your dissatisfaction, will always be eliminated more rapidly if you provide developers with relevant information tactfully.

“It’s still not working!”

Developers who are invested and professional are not oblivious: if the program would not be working at all, they would have realized it. If they did not notice anything, it must be working on their environment. Thus, it means that your environment is different from theirs or, as a user, you do something unexpectedly. They need this type of information. Indicate it in your bug report even if you are not sure if it’s relevant.

So far, you must think that I blindly and exaggeratedly defend development teams. True, because I consider that any developer worthy of the name should never ever overlook the slightest bug in an application that has been delivered and that is being used. Remember, I’m talking about invested professionals! No matter the experience level of developers, the profession must foster technical and human excellence and never ignore quality. (This theme is recurring; it’s the subject of many posts on this blog.) If bugs are recurring, it’s obvious that the team is facing insuperable impediments. Therefore, the team should be coached in order to review their practices and their soft skills.

Bug reporting—the recipe

Firstly, the goal of the exercise is to allow the developer to reproduce the bug. To do so, he must run his own copy of the program, perform the same steps as the user, and have the program crash in the same way as it happened to the user. Once he succeeded, he can than resolve the bug.

First of all, regardless of the communication tool or channel being used, the title of the bug report must be meaningful and specific in order to outline the context of the bug. For instance, “The X queries in the Y context are KO” is more accurate than “The Z application is not working!” You must also make sure to address the message to the appropriate addressees. Furthermore, if it is relevant, give information about your workstation and your work environment (operating system, screen resolution, etc.).

Then comes the description! Make sure to indicate the process and steps made for the bug to occur. If it’s a graphics program, indicate the buttons you clicked, as well as the sequence. If it’s a program triggered by a command, indicate the exact one you used. A complete transcription of the commands you entered and the answers returned by the computer are quite useful to learn about the bug. You can also attach files to compare the bug with the expected results (screenshots, data export, etc.).

Here is a template that you can use!


  1. I go to the home page.
  2. I enter my username in the Name field.
  3. I enter my password in the appropriate field (the exact password indicated in the reminder I received on February 1.)
  4. I click on the Login button.

Observed result: A message is displayed indicating that the information is invalid, and I cannot access my user space.

Expected result: I should access my user space.

In short, be specific and procedural. Do not worry if, at the end, your report looks like a recipe. On the contrary, it means that the quality of your bug reporting is good.

Finally, do not forget the usual thank you.

Go ahead! Do not hesitate to share this post before your next interaction with the technical support team . . . and see the bugs disappear! 😉

Previous post

What?!? …is beyond active listening?

Next post

Beware of buses!

romain trocherie

Romain is a Scrum Master at Pyxis Suisse. He helps teams reveal and develop their full potential. He is also known for his ability to experiment, inspect, and revolutionize processes. Contact him to find out how he can contribute to the success of your teams.

No Comment

Leave a reply

Your email address will not be published. Required fields are marked *