How to Write Good Bug Reports
In software an issue is typically referred to as a bug, every platform has it's issues some known and some not. Whenever you're using an app, website, etc. and you encounter an issue that you want to let the developers know about it can be difficult to communicate the issue in a way that makes it clear to the developers what exactly happened. From another point of view, when developing a platform it's common for non-technical teams to want to report issues to their technical team but all too often the reports are short and don't provide enough information for the development team to accurately identify the problem areas. In this article we'll discuss how to write good bug reports as a non-technical person, why it's important to do so and outline a template of sorts that you can use to make things easier.
Why spend time writing good bug reports?
The systems behind apps and websites are often very complex and involve many layers of code and infrastructure components that make up the product. Large platforms have millions of lines of code spread across hundreds of separate projects all working together. Often times specific people or teams are working on specific parts of the system. This complexity makes it pretty difficult to pinpoint an issue if not enough detail is provided. In a user context, this may lead to the issue being dropped and never resolved and in a business context this will lead to longer fix times since the developers are tasked with tracking down the issue in the large and complex system and that's like trying to find a needle in a haystack. To make matters worse, the developer tasked with identifying the issue might not even work on the part of the system that the issue is in so the issue might get shelved or passed around to many developers all trying to find that needle in the haystack.
What should I include in a bug report?
In general, it's a good idea to include as much information as possible. The less technical you are the more information you'll want to include so that you cover all the bases. This information should include, at a minimum:
- A description of the issue
- What steps you took to find the issue
- What device, web browser, operating system you're using
- Internet connection speeds at the time of the issue happening
- Screenshots or video of the issue happening
- Account information (email, username, etc.)
It's important to be as detailed as possible with all of this information as well even if it may seem like too much, the more information the better it is for the team behind the product.
What if I don't understand any technical subjects?
That's totally fine! Development teams expect this and we don't expect bug reports to include very technical information. Usually we also use the product and can identify potential problem areas just by reading your report and walking through the steps that you took to find the issue.
