Even the most sophisticated and tested applications will fail at some point, so we better be ready to respond immediately. This article will help you structure a practical bug reporting process for the Engineering team.
Failures are a given and everything will eventually fail over time…
Dr Werner Vogels, Amazon CTO
Reporting bugs is a detective job. We have to:
- Interview Customers (victims)
- Gather facts and collect evidence
- Write detailed reports on findings
Our goal is to narrow down the scope of the issue and help our Engineering team reduce Mean time to recovery (MTTR).
Interview Customers
When interviewing Costumers try to put yourself in the User’s place, and to relate and understand where they are coming from. Empathy is primordial for transmitting security and trust. Depending on your product, they may be anxious and concerned about their data and the negative impact on their business.
Sometimes the simple and common steps result in the shortest path to a solution. Here are a few things you can try:
- Reload the page
- Clean the cache and cookies
- Run an internet connection speed test
- Try on different browsers
Gather facts and collect evidence
When no in-app bug reporting tool or automatized debugging data collection is in place, make sure to gather this information to help your team troubleshoot issues:
- Screenshots / Video recordings: An image worth a thousand words
- Device / OS and Browser: https://www.whatismybrowser.com/
- URLs: Where is the issue happening?.
- Logs: Extract the logs displayed at the console tab in the devtools panel of the browser
- Data samples: Gather data about the action or transactions to reproduce the bug
- User details: When possible without disclosing sensitive information, collect all data on users reporting the issue
Write detailed reports on findings
Once we gather all information is time to report our findings to the engineering team in a structured and agile format. To do so, here is a template you can use:
### <!-- title goes here -->
#### Severity
<!-- MINOR/MAJOR/CRITICAL -->
#### Description
<!-- description goes here -->
<!-- link to screenshot or video (an image worth a thousand words) -->
#### Environment
URL: <url goes here>
Stage: <dev/staging/qa/prod> (if applicable)
#### Steps to reproduce it
Steps to reproduce the issue:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See an error
#### User details
<!-- When possible without disclosing sensitive information about customers -->
#### Browser / Device
<!-- https://www.whatismybrowser.com/ -->
#### Logs
<!-- Paste console logs in the block below -->
#### Additional context
<!-- Add any other context about the problem here. -->
After reporting the incidence. Here are some common questions to ask the engineering team to report back to the User
- Could we mitigate the issue with a temporal solution?
- Is it a functional or technical issue?
- Have we experienced it before?
- Is there an ETA to solve the issue?
Conclusions
Every time a user encounters a bug before we do, it damages their trust in us as a company. Ensure to implement monitoring, metrics, and alerting systems to prevent them from finding bugs before you do. However, whenever your application fails, we hope this article helps you improve your detective skills and the Engineering team response speed.
Useful links
https://www.helpscout.com/helpu/art-of-troubleshooting-support/
https://www.atlassian.com/incident-management/kpis/severity-levels
https://en.wikipedia.org/wiki/Mean_time_to_recovery
Top comments (0)