Bug Reports aren't just for developers

I've read a lot of bug reports over the years, maybe that says something about my coding? Maybe I shouldn't admit that?

For a software developer, having someone tell you what is wrong with your pride and joy is often confronting.  It can be challenging to stay positive and mature about it. Check your ego at the door is some advice I once heard about designing, building and delivering a software solution.

Dealing with bug reports is however one of the day's chores. One you'd prefer not to have to deal with. You should of course welcome the opportunity to correct a mistake in your beloved system and make the world a better place, but the truth is, you really wish they just weren't there.

So once you've steeled yourself for the task of opening that next bug report and you've summoned up every ounce of reasonableness, empathy and altruism you possess, it is supremely frustrating to then have to spend more time, sometimes a lot more time, playing detective and deciphering bug reports which can often amount to nothing more than some observations of what coincidentally happened the last time they ran your program.  Maybe they're not quite sure exactly what steps they took, or weren't quite paying attention, or didn't realise they were supposed to be. This is the difference between a user providing an account of something that just happened on their computer to help desk or tech support. It's their job to investigate and solve, but a software tester in a development team reports a bug in order to get it fixed.

Testers, like programmers, are part of the development team, contributing to finding, analysing, identifying, documenting and eradicating problems. In small teams especially though, it's easy to overlook this important role and just rely on some people who are on hand and "know the system" well enough to "test it" for you.

For a developer, sifting through paragraphs of observations and screen shots that someone has "noticed" just to get to the essence of a problem that you wish wasn't there in the first place, takes all your resolve. You really have to want your product to be better. In these moments, the risk to the software product, the team and the overall betterment of the world in general, of losing the opportunity to fix a genuine issue is high. Making me work incredibly hard to understand what you are saying, when I'm already looking for any reason I can find to reject your point in the first place, is not playing the team game.

What is even more frustrating than this however, is to have a previously fixed bug returned to you, with some rider attached, like a bill in the US parliament, just because whoever was testing it happened to stumble across something else while running through a test for this item.

My latest message to the team, and it is working, is...

Bug reports aren't just for developers... they're for all of us. They benefit of the whole team and the product.

Someone has to test this again , someone may need to use this resource - the bug report, this small artifact, to glean some information from it some time in the future. It is also the goal of the whole team to identify these issues and communicate them efficiently, get them fixed, and move on with confidence in the product, for everyone. It needs to be concise and clear for many reasons over and above just making some precious developer's life easy.

So my tips for a good bug report:

• A brief "punchy" title that states the problem in it's most serious case, without exaggerating, lying or over stating the issue.


• A description that explains the title, and gives a little context. This is not always necessary - only do this when it adds value (which is when the "punchy" title needs some clarifying).


• Reproduction procedures that describe how to reproduce the bug in it's most simple form. Steps that once followed and no longer result in the described issue, mean it is fixed across the board. This is the key. Show me the most succinct way to reproduce the problem you've found. Don't include 8 other steps, unless the issue only occurs if you do each of them, in a specific order. This is because, to fix a problem, you need to get to the heart of things, and fix the underlying fundamental problem.


• Desired outcome - this one is not mandatory either, because quite often it will simply be "that the error doesn't happen", but sometime developers will need to know, your were expecting "X" or you require that "Y" doesn't happen there.

That's it. That's what I need to know, to fix the problem. Someone on the team is going to do this work. The more the load can be spread, the quicker things will get done.

Oh, and by the way, don't underrate how hard this is. Succinctly describing what you've discovered, and doing all the extra analysis to eliminate superfluous information, discover contributing factors and isolate a problem, is hard - as hard as writing the program, but remember, someone on the team is going to do it before the bug is fixed. It cannot "not" be done - the more that can be done early in the process, the better.

The good news is, the bug reports are improving. As a result, I think the product will too.