The Art of Bug Reporting

The vagueness of the “it doesn’t work” report means less than nothing — the issue could be literally anything — the website could be down, the signup screen could be broken, the app could unwittingly be taking naked selfies of the user and e-mailing it to all their friends — there’s just no way of being able to tell.

Like it or not, mistakes are an inevitable part of all software.

Many mistakes can take hours to be corrected and it is impossible to deduce what the problem is without a good report of the problem.

Image for post
Image for post

Reporting Bugs — the Right Way

So here is how to write a bug report that helps narrow down the problem, makes developers happy and streamlines the process of making your software just… work.

Bug Summary

What is the problem? A bug summary should provide a quick snapshot of what exactly the issue is. It has to be precise.

Try to find the right words to describe the summary that would give the information directly. Generic statements like “not working properly”, “not working as expected” etc., must be avoided.

Where is the problem? If it’s a website, copy and paste the URL. If it’s not, give the name of the screen you are on.

What environment are you using the software in?

Are you on a PC or a Mac? Firefox or Chrome? iPad or iPhone? iOS or Android? What software version(s)? What browser plugins do you have installed? What crazy software are you running in the background?

Describe the problem (obvious)

A bug should always be written in a clear, concise and precise manner so that it gives an exact location of the bug in the extensive/exhaustive software map. I reiterate that this not only improves the quality of software but also reduces the cost of testing and developing the software to a great extent.

Expected result — Suggested fix

Say what you expected would happen with the steps taken and what really happened. Do you think you know how this should be fixed? Great! Save developers some time and confusion and describe how you think it should be fixed here.


If you can see the problem, capture the moment. There is nothing better than being able to see the problem by ourselves. And if there are already annotations in it, you will have nailed it!

Image for post
Image for post

Spread love to developers

If you find something wrong — no matter how alarming it seems, stop what you’re doing, take a step back and write a decent bug report.

As easy as firing up the email and document the incident with love. Don’t just call up or send a one-liner message.

So now when you check out that shiny new software released and something breaks, you know how to get it fixed faster, more effectively and without frustrating anyone. You become a helpful part of a team, instead of a clueless outsider and hey, maybe you learned some things to make you a more software-savvy person in the process.

Sincerely, a developer.

Written by

Software developer @

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store