Bugs reporting and troubleshooting

Ivan Horomanski — Mon, 13 Dec 2021 08:46:37 +0000

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

DEV Community: Ivan Horomanski

Bugs reporting and troubleshooting

Interview Customers

Gather facts and collect evidence

Write detailed reports on findings

Conclusions