How to Improve Your Bug Reports

There are days when your bug reports are the only communication a programmer receives from the outside world (ignoring e-mails, chats, Facebook, Twitter and mobile texting); make them count.

Understanding the Problem

As much as you can, try to identify the source of the problem. Say you’re complaining that data aren’t written to the database. Try to see if the software is not responding to the request; or if it’s trying and failing to write to the database. Then see why it’s failing: are the INSERT queries even performed? Are they garbling up the data? Is there a mismatch between the table’s fields and what the software is looking for? To really identify problems, you need to be willing to dig in. Don’t be afraid to read logs, XMLs, and the database queries and existing data.

Distinguish between a bug and a missing feature. Something going wrong is one problem; something being impossible is another problem, and will usually pass the first three circles of hell before reaching a programmer. Who gets to handle what isn’t your concern; but you need to clearly state “This was meant to work and doesn’t” (bug), “This was supposed to exist and doesn’t” (someone skipped a page in the specification?) or “I think we should add this ability” (request for a new specification).

Explaining the Problem

First and foremost, don’t assume the programmer knows the program. I know this sounds cruel, but programmers often know just their tinny bit of code, and when you send them bug reports talking about windows and fields and buttons, you may as well be speaking Urdu. Give details of where you were when the bug happened and explain the process. Where to begin it, what steps to take, where to go from here. But you don’t need to go into too many details here; the details will come in the next section, when you recreate the problem.

Even if you know the programmer knows the software like the back of his hand, don’t assume the problem is obvious to him. Explain what you wanted to have happened, and – particularly if you’ve found something wrong with the specification – why you expected it to happen. Sometimes, your programmer will simply not understand how his beloved code failed to satisfy you.

Recreating the Problem

Sometimes you can’t recreate a problem; this is often the case with elusive crashes. You need to report them anyway, since a crash is never the correct behavior, whether you’ve any idea how you caused it or not. A bug report saying “I can’t recreate this” is better than not reporting the bug at all. But this should be an exception to a rule – because if you can’t recreate your bug, how on earth do you expect anyone to find out why it happened?

You should always make it perfectly clear how to recreate your bug. Don’t give general details (“Er, I was in this window, and it, like, completely didn’t do what I wanted!”). Give clear, concise steps. I entered window X. I did A, B, C, D. I saved. I entered a second window called Y and tried to read the data. The data were not available.

Superficially, this seems like “don’t assume the programmer knows the problem”. But recreating the problem requires more details than simply explaining it. When explaining, you can say “data were not readable from the database while working in window Y”. When recreating, you should specify what you tried to enter, because bugs may occur only with certain types of data, or only with certain combinations of actions; where you tried to enter it, because there may be many places that allow entering the same data but only one is faulty; what other actions were performed in the middle, etc’.

If you can, recreate the scenario up to the last-but-one step. In the above example, do everything in the first window, and leave the data as-is for the programmer to try to read in the second window; if the problem is reading, not writing, he’ll have everything he needs to find the reading bug. This will prevent recreation mistakes, and will reduce the chances of the programmer complaining about bad bug reports.


In the end, the best way to improve your bug reports is to learn from your mistakes. Notice what questions other people are asking you and see if you could have answered them in the report. If the answer’s Yes, then add that information to the next report. At the very least, it will show you’re trying, and will get you some good will.

This entry was posted in Articles, QA and tagged , , . Bookmark the permalink.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s