How to Report Bugs Like a Boss

A small bug in production

As unfortunate as it sounds, bugs happen. Let’s just embrace this fact and move on think about to handle them properly instead of how to prevent them (this is a whole different topic).

Let’s have a look on a typical situation which occurs oftentimes in many software development teams — reporting a bug. This is something that sounds too trivial to talk about, but this is not true.

Please note that for the sake of simplicity I will be referring to a bug report when talking about bugs. Bug as bug report, as documented or reported software defect, not the defect itself.


For us to be on the same page, I will be talking about a hypothetical project setup:

  • 1 engineer, 1 QA, 1 PO
  • a product (project) is fairly simple — it’s a blog (let’s say the one you’re reading)

So what is a common lifecycle of a bug report?

When someone spots a bug (a QA or a PM), he immediately documents it, right? Let’s have a look at how this immediate report might look like:

Screenshot 2016-03-22 20.39.38

Does it look familiar?

Although such description totally makes sense for the person who reported it, it has a lot of subjectivity there. Since reporter is kind of “deep in the context” at that moment, the content of a bug totally makes sense for him. Sure — he sees the page with the bug, he knows how he got there, and all those steps seem obvious to him. But obviousness is a relative thing, and that is the problem.

I am pretty sure you know what happens next, but let me analyse it.

“Expensive thinking”

A bug report then gets into the hands of an engineer.

By that moment, the engineer has completely different context of perceiving reality. So in order to understand the issue, he has to dive deep into the new context. This involves some thinking, which sounds trivial, but which is not so trivial when you think about it. I apologise for the pun, let me explain it.

The engineer is trying to analyse the bug. During this process he is putting himself on the reporter’s place. I call this process “expensive thinking”. It is expensive in terms of the brain resource. Now, this is a good practice and it gives an engineer a lot of flexibility. The only problem is that a bug is not a story, and we should avoid the flexibility of perception a bug by any means. And of course, we should always consider whether to estimate bugs or not.

Simply saying, a bug should be as descriptive and detailed as possible.

Communication subjectivity

This is my favourite illustration about the communication from the Management 3.0 by Jurgen Appelo
book. The idea of misinterpretation during communication of your thoughs is similar to the process of perceiving a ticket differently.

It might not sound like a big deal to you, no. But let’s see what happens next, when this engineer has to deliver more bug fixes (which is quite often the case).

He repeats the same process of “expensive thinking” over and over again. Don’t get me wrong, I am not against thinking as a process, I am just against any waste in general — be it waste of time, waste of money or waste of intellectual resources.

“30 Minutes Clarity Debt”

So what happens in this particular case is the following scenario. Our engineer analyses the bug description and tries to find the answers on the following questions:

  • Which part is it about — frontend or backend (admin)?
  • If that’s admin part — which user account should be used?
  • What was the post id?

Now, to get answers on those questions he is going to spend some time either by trying to find those answers himself, or by asking the reporter. Depending on how much time passed, the reporter might not even be able to recall now all the details.

So the engineer ends up spending 30 minutes of finding the answers.

You probably already see where I am heading to, but it’s not the end. Once the solution is implemented, the bug goes to the QA for approval. Guess what, the QA guy now has the same problems, and he is going to spend the same time trying to figure out all the “what?” mentioned above.

The 30 minutes “clarity debt” has just doubled. And I am not going to tell you how easy this amount scales up when there are multiple bugs with the similar description quality.

How to avoid

Now rewind.

Let’s say a reporter spent more time documenting the context. So now we have the following description:

proper bug description

As you have guessed by now, when our engineer gets this bug report, he spends no time figuring out how to reproduce the thing and focuses on the solution instead. Same applies for the QA guy.

It’s a win-win for everyone!


Avoiding waste is fairly easy. One simply has to always specify the context of a bug. Switching the context is the most expensive underrated brain operation.

By specifying clear steps to reproduce, some notes on the actual/expected behaviour we are playing it safe and winning some time. This time might not sound like a lot (indeed, it was much exaggerated in my example), but this debt stacks up to enormous amounts.

I repeat, don’t forget to reflect existing context on paper in the ticket.


Happy estimating!

Also, if you’d like to receive new posts straight into your inbox — please, sign up for my mailing list.