How to write a good bug report

When something doesn't work the way you expect with your software or website, you want it fixed as quickly as possible. 

As developers of that software or website who take pride in our work, so do we! But as with any aspect of development, communication is key. It can be hard to describe exactly what went wrong, but if you're able to provide a thorough account of the issue at the beginning, we can in turn provide a much better solution (and much faster). 

With that in mind, we've compiled the following tips on how to write a solid bug report. (See an example at the bottom.)

Bug report template

1. Provide clear steps for how you arrived at the error or issue, even if it seems obvious to you.

WHY steps to reproduce an error are important

• Reproducing a bug often takes more time than actually making the code changes that fix it; around 80% of the work is figuring out what went wrong in the first place! Clear steps to reproduce mean we can cut that time down significantly.
• Having a thorough outline of what went wrong also makes it much easier for our QA team to to verify afterwards that the bug has, in fact, been fixed.

HOW to provide steps to reproduce an error

• Write a step-by-step list of how you discovered the issue. Include details like the URL, which user was logged in, the browser and device type, etc.
• Not-so-good example: "Log in and try to see your products."
• Better example: "Log in and click 'My Products' in Chrome."
• Best example: "Log in and click the 'My Products' tab in the top navigation bar. I was using Chrome on my Macbook Pro."

2. Explain what you expected to happen after taking the steps outlined in section one.

WHY we want to know the expected behavior

• Oftentimes, a bug is not really a programming defect; maybe it's a misunderstood specification, or maybe the feature is poorly designed or causes unexpected behavior (for example, you expect that clicking "save" after editing a product description will take you to the product page, but instead, you return to the homepage). 
• If it is, in fact, not a programming defect, that doesn't mean it isn't a valid bug report! It just means we'll tackle the problem differently, and the quicker we can triage, the faster we can fix it.

HOW to explain the expected behavior

• Concise, deliberate language; "I expected to see a list of all the users that match my search" might sound like enough information, but "When I searched for 'sam,' I expected to see 'Brian Samson' in the user list and didn't" is even better.
• Include why you expected specific behavior.
• Not-so-good example: "I expected to see Janet's profile when viewing 'active' users." --> This leaves room for misinterpretation; it could be a bug in the code, but it could also be a difference between what you as a user consider "active" to mean versus what the computer (or developer) thinks "active" is supposed to mean.
• Better example: "I expected to see Janet's profile when viewing 'active' users because she's finished."
• Best example:"I expected to see Janet's profile when viewing 'active' users, because as someone who has completed her training, I expected her to be considered 'active'."

3. Tell us what actually happened after taking the steps outlined in section one.

WHY we want to know more details

• In the first section, you described what prompted the error; in section two, you described what you thought should've happened; for this last section, we want the nitty-gritty of what actually happened: the bug itself. 
• The more detail you can provide, the better we can determine the true nature of the bug: is it unclear UX? Bad data? User error? A mistake in the code? The faster we can triage the error, the faster we can fix it. 
• This section also helps us figure out the scope of the problem, and whether it's specific to a device (like Android or iPhone) or a browser (like Firefox or Chrome) or an operating system (such as Windows or Mac). 

HOW you can best tell us what happened

• Include: screenshots, the URL or URLs (if the error happened on a website), the exact error message or messages (if present), what device/browser/operating system you were using, possibly even time of day or day or the week
• Be as specific - and detailed - as possible. It's unlikely that you could give us too much information. 
• Not-so-good example: "When I hit 'create', nothing happened."
• Better example: "When I hit 'create', it didn't work, and gave me an error message."
• Best example: "When I hit 'create', it reloaded to the 'new account' page with this error at the top of the page in red: 'error saving Entity#{User}: Database connection failed on line 32'. I've attached a screenshot showing the error."

Sample bug report