The Origin of "Bugs"
In 1946, United States Navy programmer Grace Hopper was working on an early computer (the Harvard Mark 1) when it had some unexpected output. In Grace's words:
"Things were going badly; there was something wrong in one of the circuits of the long glass-enclosed computer," she said. "Finally, someone located the trouble spot and, using ordinary tweezers, removed the problem, a two-inch moth. From then on, when anything went wrong with a computer, we said it had bugs in it."
The term "bug" is now mainstream. Whenever a system doesn't behave as expected, it may be because:
Part of the system is not physically functioning (e.g., a server has stopped working).
The logic provided to the system was wrong.
The logic provided to the system was incomplete.
The logic provided to the system was ambiguous.
An insect has gotten stuck in our relay (kidding!).
Test Releases for Bugs
Many development teams may have one or multiple members responsible for quality assurance, whose job is to check or test that a product version has met specified requirements before being released to the public. They might be called a tester, QA engineer, or QA, and they test for defects (bugs) before any releases. While many companies have quality or testing as separate teams, quality and the accountability for creating it are internal attributes of effective teams. Having a separate team test the work from the one that created it can lead to delays, conflict, and an overall lack of focus on high-quality work. At worst, it could lead to finger-pointing, increased risk for the company, and unhappy customers.
As a product manager, if there is a release, you test. It's part of your job! Others will also test, but it's your reputation on the line, and often you know the requirements better than anyone else. Don't think otherwise.
It's best to write tests before work starts on features. Then, test on completion to be satisfied that the team has delivered what the customer wants.
Write a Bug Report
Imagine you have received the bug reports below. Can you see anything wrong with them?
"When I remove an item from my shopping cart, I don't see the total order update."
"The confirm account email looks broken in several email clients."
"The monthly revenue report is wrong."
Here is a good question to ask: "If I received this report from somebody else, am I sure I would know what they are describing?"
If you find something wrong with your product, it's your job to write a description that is:
Easy to understand.
Easy for the person receiving the report to see what actions you took (and in which order) so they can try to reproduce the problem.
Clear about what product behavior they expect (if the system did work perfectly).
Contains all the information to solve the problem.
Let's imagine you have been told that "the monthly revenue report is wrong." What is the first question you would ask? Probably something like, "What exactly is wrong with it?" It may seem obvious, but most people who write bugs are guilty of being ambiguous in their descriptions.
Let's imagine that someone says, "When I remove an item from my shopping cart, I don't see the order total update." To find the problem in the product, you would need to know what item was removed and what other items were in the shopping cart at the time. You may also need to know the total before the item was removed (and after), what browser the person was using, and other details.
Let's now look at what a good bug report should include to help developers quickly find, replicate, and fix the problem.
Identify Elements of a Good Bug Report
Steps to reproduce
Device and OS
Links
Expected behavior
Actual behavior
Screenshots
Include Steps to Reproduce
This should be a numbered list of the steps that you took to notice the problem. The person who opens the bug report will try these steps and fix the problem if they can see it. But if they cannot, there is nothing they can do. This first step is called "replicating a bug." The actions you describe are vital to ensuring that you can replicate bugs before fixing them. Check out the example below.
The steps to replicating a bug are:
Log into the site as a returning user.
Add a pair of Nike Air Force 1 '07 to the shopping cart.
The cart shows a total of $90.
Then add a Jordan Dri Fit Air Men's Fleece ($100).
Remove the Windrunner jacket from the shopping cart, and the total shows $100.
Add Device and OS
Are you using an iPhone or Android? Are you visiting the site on mobile or desktop? What is your browser version?
Use Links in a Bug Report
Writing "Log into the site as a returning user" and "Add a Dri Fit Air jacket " may be reasonable descriptions. However, it's even better to use links to make sure that everyone has access to the items.
Steps to replicate are:
Log into the US site with username: buygreatstuff and password: logmein123.
Add a pair of Nike Air Force 1 '07 to the shopping cart
The cart shows a total of $90.
Add a Jordan Dri Fit Air Men's Fleece ($100).
Remove the Dri Fit Air jacket from the shopping cart and the total shows $100.
Now the process of replicating is easy. It's little more than clicking some links (much better than searching for products!) and doing a few actions.
The simpler it is for your tech team to reproduce the problem and see it happening, the more likely they will fix the bug quickly.
Note Expected vs. Actual Behavior
Your bug report will be easier to understand if you write two sections: expected behavior and actual behavior. So let's revisit the steps with these two sections added!
Steps to replicate are:
Log into the US site and log in with username: buygreatstuff and password: logmein123.
Add a pair of Nike Air Force 1 '07 to the shopping cart.
The cart shows a total of $90
Now add a Jordan Dri Fit Air Men's Fleece ($100).
Now I remove the Dri Fit Air jacket.
Expected behavior: The cart total shows $90 (shoes=$90 and the jacket=$100. Then removed the jacket).
Actual behavior: The cart total shows up as $100.
Include Screenshots in a Bug Report
A screenshot is helpful because it shows:
Proof that you saw the problem.
Where the problem is on the screen.
You can use a tool that also lets you put arrows and text into your screenshots. When you annotate your screenshots this way, it becomes easier for others to see what and where your expected and actual behavior should be happening on screen. Tools like Snagit, Paint, and others can help you annotate screenshots, including adding text, arrows, and shapes.
In the next lesson, we will look at using Jira for creating a bug report. It's another Atlassian (the makers of Confluence) product and is one of the most popular bug tracking tools on the market (so it's good for you to know!).
Let’s Recap!
Writing a good bug report is critical to help prevent future defects and to encourage a collaborative culture on the team.
Some elements of a bug report that we should keep in mind are:
Steps to Reproduce
Expected Results vs Actual Results
Environmental factors (what version, what device type, time, browser, Operating System, etc).
These are all critical for a developer to understand so that they can properly research the cause of the bug/defect.
Screenshots or even video recordings of the bug/defect can be extremely helpful and aid in timely identification and resolution of defects.
Now that our bugs are properly noted, let's learn how to use JIRA in the next chapter!
Additional Resources
Free alternatives to Snagit.
Paint for Windows and a hidden version on Mac.
