A short guide on reporting bugs

I’m a user and a developer. Every day I see people reporting bugs and problems, either in support forums or on Facebook or, less common, a dedicated bug reporting tool like mantis. This often goes along with complaints about not being heard, the bug not being taken seriously or a general lack of feedback from the developers. Since I see users doing a lot of typical mistakes when reporting bugs, I thought it might be helpful to write a short guide on how to maximize your chances to get problems fixed (knowing that it’s unlikely that the people I’m referring to will ever read it). So, yeah, it’s one of “those” guides.


General facts to keep in mind when reporting a bug:

  1. Developer time is precious. Yes, reporting bugs is work and takes time. Reading bug reports, however, is work too. Each minute a developer spends reading a bug report he can’t do anything else.
  2. The number of users. An app may have thousands or hundreds of thousands of users, but there are rarely more than a handful of developers, which means that those people have very little time to spend on the individual.
  3. Priorities. Developers have to make a decision on which bugs are more important than others. If your bug is an annoyance but doesn’t break anything it’s more likely that it will not be fixed immediately (or at all). Your problem may be important to you but not for the 99.999% of other users. However, you should report it anyway, since sometimes little annoyances are fixed when there’s another related issue in the same place.


How to report a bug efficiently (aka, “good habits”) :

  1. Be explicit. Don’t skip steps and don’t assume that someone reading the bug report knows what you’re doing or knows what the error message you got said. Every single step in a bug report can be valuable information. A few more minutes spent by you may save hours of time for the developer. If a developer has to reply and ask for more information on a specific step, you will have a much lower chance of being heard.
  2. Make it short. It sounds contradictory to what I just said but it is not. Remember, developer time is precious. Try to pack your report with information but don’t write an essay on how to open a file. A short and precise report has higher chances of being read and understood than something you need 30 minutes alone to understand. Use bullet points instead of whole sentences if that sufficiently describes the problem. Spend time on refining your report, don’t waste developer time.
  3. Provide examples, sample scenes, screenshots, videos. Whatever helps to make clear what happens when and how is great. A video can be great to quickly show a problem you’re not able to sufficiently describe in sentences, especially if you’re not a native English speaker. Again, if a developer needs to spend time on trying to understand or reproduce something, your chances of a fix decrease. Sample scenes are particularly helpful since developers often have tools for narrowing down causes of an issue, tools a user usually does not have access to.
  4. Use the bug reporting tools and services your software or vendor provides. Many companies allow you to log in to a bug reporting tool like mantis to report bugs. This makes it much more likely that a developer will read your report. A forum post or thread is easily missed and you don’t want the developers to spend their time on looking through endless forum threads to find your report.
  5. Stay polite and professional. Yes, bugs are annoying and often times you just can’t understand how “something stupid as this” could be happening but software is complex and you, the user, are usually not aware of how things interact with each other. Developers are people (..most of the time) and people don’t like being yelled at. You’ll rather end up being ignored than put on the top of the todo-list.
  6. Don’t expect expressed gratefulness for reporting bugs. Developers value bug reports highly but are usually not communicating it much (you will stop doing that after a couple of hundred reports). There is practically no experienced developer with a passion for the software he or she develops and does not want users to report any bugs they find. A found and fixed bug makes the software more stable, more valuable as a product and easier to maintain.
  7. Subscribe to the thread or mantis report to be able to give feedback when a developer needs it. A lot of bug reports are being closed after a few weeks or months because a reporter doesn’t respond to questions about the issue.


P.S.: How to NOT do it :

“XYZ doesn’t work!11!!”. Helps nobody, wastes time. If it is indeed a simple one like pressing a button and it doesn’t do anything, say it. A lot of those reports are often user errors and are more likely to be ignored. Developer time is often wasted on clarifying user errors (which however might point towards a design problem), time that could be spent on actually fixing problems.