February 24, 2022

How to report better issues?


Rest assured: I'm not trying to embarrass you. If you're reading this, it means you're already taking the necessary steps to fix your issue-reporting game! The trouble is that we often don't realize how much time we waste when someone reports an issue in an unclear or confusing way. The best thing to do is to use a standard format and follow a few tips for including all the necessary information. In this article, I'll show you some of my favourite techniques for reporting better issues and submitting clear bug reports.

What is an issue?

An issue is a problem in your app. It can be something wrong with the design or an error that prevents the user from using it. Issues can also be things like performance problems and bugs—things that may not seem like problems at first glance but may impact users' experiences with your app nonetheless.

The most important thing about issues is that they are specific and actionable. They tell you what needs to be done, who does it, when it needs to be done, and why it's crucial for you as a developer or designer to move on this issue right now (or why this issue isn't worth spending time on).

What to include in an issue?

Here are some main things you should include in your issue:

  • Steps to reproduce the issue.
  • Expected behaviour and the actual one.
  • Screenshots, logs or other relevant data can help us understand what went wrong.

Steps to reproduce the issue

The best way to report an issue is to follow these steps:

  • Describe the steps to reproduce the issue. Make sure you don't skip any steps. If you do, your issue will not be beneficial for us. We might have to ask you some questions about your setup to understand what's happening.
  • Don't make assumptions! For example, if a button doesn't work, don't assume it's because of something wrong with the button itself (it may be related to another part of the interface). Instead of making assumptions about how things should work and then reporting those as bugs, describe what happened and let us figure out why it happened—that way, we can fix everything correctly!
  • Don't assume that the person reading the issue will know what you are talking about or have the same context as yourself. Explain everything in detail so they can reproduce and investigate your problem themselves instead of having them guess their way through it based on incomplete information provided by someone else (you).

Expected behaviour and the actual one

To report an issue, you need to be able to explain what you expected to happen and what happened. You'll also need to explain why it was unexpected and what you would like to see happen instead. For example:

  • I expected the text-based game "Get the MacGuffin" by [name of creator] to have a simple interface that allowed me easy access to all options within the game. Instead, I was confused by the number of buttons on-screen at any given time and had trouble finding my way around this new title.
  • I'd like for there only to be two buttons available: one for starting up your adventure with a character of your choice and another button that leads back out into the world so players can explore without feeling trapped behind these walls again!

Screenshots, logs, etc.

Here's a quick rundown of the types of information you'll want to provide:

  • Screenshots, if applicable. These can be useful for showing exactly what you're talking about. If you've encountered an error message, include a screenshot of that error message—this is especially helpful if there are multiple error messages, as it might not be immediately obvious which one is relevant without seeing them all in action. If you think including a screenshot will help clarify things for the developer investigating your issue, go ahead and include it!
  • Logs from your device or service (if available). These logs contain information about your device and its interactions with other services. Logs may also contain diagnostic data such as network traffic or memory usage.

Writing clear and descriptive issues can save a lot of time for everyone in the team!

Writing clear and descriptive issues can save a lot of time for everyone in the team!

When reporting an issue, it's essential to use as much detail as possible. When you write, "This is broken," it's not very helpful. Instead, explain exactly what is broken: "The homepage doesn't load at all." That way, the person who receives your report knows exactly what needs to be fixed and can start working on fixing it immediately. If the entire team uses this approach when writing issues (and we hope they do), then everyone will have a much better understanding of what needs to be fixed and how best to fix it.


Writing good issues is only half the battle. You also need to ensure that the issues you post will be seen by others and addressed appropriately. To do this, you must use proper tagging and follow best practices for writing clear, concise titles and descriptions.

In addition to these best practices, I hope this article has given you a new perspective on how to write good issues — one that will help improve your workflow and those around you!

In this brief article, we discussed the importance of writing clear and descriptive issues to save time for everyone in the team. We started by defining an issue and then listed some common things that should be included in an issue report.

no credit card required, cancel any time