Issue reporting is not solely the domain of most QA departments. As such, many different people can be tasked with reporting issues we come across on our projects. It will make the lives of those on the development side much easier if all issues are written in a consistent manner and contain a minimum amount of necessary information.
Note: This document is not intended to instruct users how to report bugs and improvements. It is intended for fellow developers, QA folks, PM's, and any other employees involved in the software design & development processes.
It is very important to have a clear separation between improvements and bugs. Trust me when I say, you don’t want to go down the path of using bugs to justify improvements, as that can wreak havoc on the numbers being reported out by your tracking software.
A bug, more often than not, represents a definable problem within some layer of your software or it’s rendering environment. Bugs typically cause your app or site to not work as expected and or display incorrectly in it’s target environment.
An improvement is a feature request that seeks to add new functionality and or improving current functionality in a way that makes your app faster, better, stronger, and all around more usable. Improvements tend to be subjective in nature and as such, shouldn’t be filed as bugs.
A simplified example:
Bug: The ‘Buy Now’ button on the shop page is un-clickable in Firefox on Windows 10.
Improvement: The ‘Buy Now’ button should be bigger and utilize a more contrasting color.
As you can see, the improvement offers little in the way of an actual problem, and is subjective in nature.
While there are many things people can do on large projects to ease the burdon on the development staff, very few are as "cost affective" as really well written, consistently structured bug reports. Exciting.
Consider the following example:
Title
---------------------------------------------------
Shop screen doesn’t look right.
Description
---------------------------------------------------
When I resize my browser, sometimes the
content in the ‘shop’ section misaligns itself.
Reporter
---------------------------------------------------
Sam Smith <s.smith@company.com>
This bug ticket is missing a ton of necessary information. When presented with tickets that are this scant on content, developers tend to do one of the following:
-
Re-assign the bug back to the original reporter asking for more information. Thus creating churn on this issue, probably kicking off tons of emails, and creating signal to noise problems for everyone involved.
-
Deploy a fix for the bug based on assumptions. This fix may or may not be what the original reporter had intended to be fixed. This in turn may cause more bugs to be filed, and or create more back and forth with the reporter.
-
Mark the bug as “Won’t Fix”, and or ignore it completely until someone comes by and yells at them. No one wants this.
-
Unceremoniously close the ticket, possibly annoying the original reporter and perhaps preventing them from wanting to continue reporting issues.
-
A non-subjective title
- Good: The main logo, when clicked or tapped, takes users to the wrong URL.
- Bad: The main logo is broken.
-
A thorough description of the problem
- Good: I clicked the company logo in the top left of the site expecting it would take me back to the homepage, instead, I was directed to http://localhost
- Bad: The company logo goes to the wrong URL when clicked.
-
Environments where the bug is being seen in
- An environment refers to what browser(s), operating system(s), and or device(s) the reporter is seeing the bug happen in.
-
An "Actual" Summary
- "Actual" is a concise sentence of what is actually occurring.
- Good: The main logo is pointing to the wrong URL and confusing users.
- Bad: The main logo sucks and I hate it.
-
An "Expected" Summary
- "Expected" is a concise sentence of what the reporter believes should be the case.
- Good: The main logo points to the homepage URL.
- Bad: Fix it! fix it! fix it! fix it!
-
What, if any, steps are needed to reproduce the bug
- Be as thorough as humanly possible here. Reproduceable steps are extremely important especially in applications that have complex UI, multiple flows, or are generally more sophisticated than a simple brochure site.
- Good:
- Open our site in any supported browser.
- Attempt to click or tap on the main logo in the top left.
- Notice the browser is not re-directed to the proper URL.
- Bad:
- Click on the logo.
-
Any supporting screen shots
- Screen shots aren't always necessary, but whenever possible please provide as many as are necessary to show the problem at hand.
- Big red arrows and outlines are typically a good idea too.
Let's consider the shop page example again, but this time with all of the above information included in the ticket:
Title
---------------------------------------------------
Shop items display incorrectly below 780px width.
Description
---------------------------------------------------
In certain desktop browsers, when I resize my
window below 780px width, the products grid on the
shop screen begin to overlap. No supported mobile
browser is affected at this time.
Desktop Browsers Tested
---------------------------------------------------
Chrome - OSX: Passes -- items do not overlap
Firefox - OSX: Passes -- items do not overlap
Safari - OSX: Fails -- items overlap
IE11 - Win: Fails -- items overlap
IE10 - Win: Fails -- items overlap
Actual
---------------------------------------------------
When the browser window is below 780px, items in
the shopping grid overlap.
Expected
---------------------------------------------------
When the browser window is below 780px, items in
the grid should either re-align themselves, use
fewer columns, or shrink accordingly based on
available space.
Steps to Reproduce
---------------------------------------------------
1. Point an affected browser to url.com/shop
2. Scroll down to the product grid
3. Resize your window below 780px
4. Notice the overlapping elements
Screen shots
---------------------------------------------------
<ScreenShot 1.jpg>
<ScreenShot 2.jpg>
<ScreenShot 3.jpg>
Reporter
---------------------------------------------------
Sam Smith <s.smith@company.com>
With the information presented above, any developer assigned this ticket will be have the necessary information to do the following: accurately assess the problem, prioritize it against other bugs in the system, estimate the time needed to deploy a fix, and get the fix deployed.
While this approach is obviously more involved and will take more time on the part of the reporter to write up and document the bug, it will end up being a net win for the team over time.
Thanks for reading, please feel free to hit me up with any questions/comments/concerns/scathing witticisms!