{"id":7393,"date":"2017-04-28T11:45:57","date_gmt":"2017-04-28T10:45:57","guid":{"rendered":"http:\/\/intercom.com\/blog\/?p=7393"},"modified":"2020-07-30T12:57:59","modified_gmt":"2020-07-30T11:57:59","slug":"the-good-way-to-file-a-bad-bug","status":"publish","type":"post","link":"https:\/\/www.intercom.com\/blog\/the-good-way-to-file-a-bad-bug\/","title":{"rendered":"The good way to file a bad bug"},"content":{"rendered":"

Great bug reports are the the oxygen of quality control. Take them away and everything turns sour.<\/p>\n

As a Customer Support Lead, I spend a lot of time in technical discussions with our customers, ranging from API debates to complex SDK edge cases. Our end goal is a happy customer, but the approach will vary from conversation to conversation.<\/p>\n

Sometimes I just need to explain something, sometimes I need to write some sample code or debug theirs, sometimes we need to update or clarify our own documentation, and occasionally I need to file a bug to get something fixed quickly.<\/p>\n

Good bug reporting streamlines an investigation for whichever product team owns it and lets them triage quickly. A repository of well documented bug reports gives valuable context if a bug re-occurs, or a similar incident happens.<\/p>\n

The features of a good bug report<\/h2>\n

\"good<\/p>\n

We use Github Issues to log our bugs, but the advice remains the same regardless of what service you use.<\/p>\n

A great title<\/h3>\n

A great title can be scanned by your colleagues to immediately get a sense of what\u2019s happening, where, when, and how. Remember, this is going to have to be picked out from a list of other issues during triage. A descriptive title will also ensure that duplicate reports of the same bug will be quickly spotted.<\/p>\n

A bad example:<\/b> User list is bust for this user
\nWhy?<\/b> How could anyone know what this is without having to click through and read more?<\/p>\n

A good example:<\/b> User list not scrollable in Linux on OSX FF34
\nWhy?<\/b> This has lots of detail including the operating system and browser being used.<\/p>\n

A concise, precise description<\/h3>\n

Be as detailed as possible as to what is actually happening, and how the user experiences it. Be careful not to take the user\u2019s description of events as gospel. Often they\u2019ll only talk about what they experience, not what is actually happening. For example, a customer might say, \u201cThe message stopped sending\u201d. Did it actually stop sending, or did the UI tell them it stopped sending?<\/p>\n

As we use Intercom to provide support for Intercom<\/a> we always link to the relevant conversation where the customer highlighted the issue.<\/p>\n

How to reproduce<\/h3>\n

To reproduce a bug you need to document the relevant conditions it occurs in and the steps necessary to trigger it.<\/p>\n

Conditions are everything from Browser\/OS\/Mail Client through to customer state (e.g. paying, new, or old). Make sure to include clear steps to reproduce i.e any actions taken on screen to cause a broken state.<\/p>\n

Label it<\/h3>\n

Labelling is also important so that issues can be prioritised. We tag bugs with the following labels:<\/p>\n

Severity:<\/b> We have labels for problems (p-levels) ranging from \u201cDrop everything and fix this\u201d through to \u201cTidy this up when we\u2019re next changing that flow\u201d.<\/p>\n

Team:<\/b> Which product team is impacted. If in doubt over which team should be notified we add tags for both. The key here is to ensure the relevant product manager and engineering lead is alerted straight away (we send GitHub notifications to the relevant team\u2019s Slack channel).<\/p>\n

Customer frequency: <\/b>Our team tag frequent issues if they occur daily or weekly. These problems may not be critical to the product (in terms of p-level) but are so frequent that it\u2019s in everyone\u2019s interests to fix it quickly.<\/p>\n

Cause: <\/b>We want to determine why this bug got in the wild and depending on the cause what we can do to make sure it doesn\u2019t happen again. Some bugs you can’t prevent but some are preventable with proper testing or QA. Example tags here includes acceptable, missing automated tests, wrong design\/dev decision or missing human QA.<\/p>\n

Console investigations<\/h3>\n

Our customer support team has many engineers so naturally we investigate ourselves before escalating. Tools like FullStory’s Dev Tools<\/a> lets us see what the console logs looked like for real visitors on our site at the time of their issue. Including console output from our investigations is really helpful for transferring context. The receiving engineer can then either build on that logic or decide its wrong and close it – either way, time has been saved.<\/p>\n

Gifs and screenshots<\/h3>\n

Screenshots are the currency of UI bugs and gifs are the equivalent for interaction bugs. If something is janky, such as a rough animation or broken transition, a Gif is the easiest way to communicate it. Show, don\u2019t tell.<\/a><\/p>\n

Check the Javascript console<\/h3>\n

If there\u2019s a problem in the UI it\u2019s always good to check the Javascript console. We have a saved reply for this, as it\u2019s such a valuable piece of information from our users. \u00a0For anyone non-technical it means hitting <Alt>-<cmd>-<J> – anything red is bad. Again, a screenshot of the offending text is valuable.<\/p>\n

Other considerations<\/h3>\n