• 10 hours
  • Medium

Free online content available in this course.

course.header.alt.is_video

course.header.alt.is_certifying

Got it!

Last updated on 5/19/20

Write a good bug report

Log in or subscribe for free to enjoy all this course has to offer!

The Origin of  "Bugs"

In 1946, a United States Navy programmer called Grace Hopper was working on an early computer (the Harvard Mark 1) when the computer's output was not as expected.  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.

Grace Hopper's first bug report
Grace Hopper's first bug report

The term 'bug' has become one of mainstream use. 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 (ok, only kidding! :) ).

Testing releases

Many development teams have a member 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. Such a person might be called a "tester", a "QA engineer", or a "QA".  Their job is to test what the development team has built for any defects (bugs) before any releases are made.

I'll add my own personal experience here.

As a product manager, if there is a release, you test. Others will also test but it's your reputation on the line and often you know the requirements better than anyone else. One of the main functions of a product manager is to test. It is your job to test. Do not think otherwise.

You should write tests before work starts on features. You should test on completion so that you are happy that the team has delivered what customers will be happy with!

Writing 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 order total 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, is it certain that I would know what they are describing?"

It is our job when we find something wrong with our product to write a description that is:

  1. easy to understand.

  2. easy for the person receiving the report to see what actions we took (and in which order) so they can try to reproduce the problem.

  3. clear about what product behavior they expect (if the system did work perfectly). 

  4. contains all the information needed 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?". This might appear 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". In order to see this problem yourself in the product, you would need to know what item was removed, what other items were in the shopping cart at the time, what the order total was before the item was removed and then after, perhaps what browser the person was using, or more details depending on the context.

Let's now look at what a good bug report should include in order to help developers quickly find, replicate, and then fix the problem.

Elements of a good bug report

  1. Steps to reproduce

  2. Device and OS

  3. Links

  4. Expected Behavior

  5. Actual Behavior

  6. Screenshots

Steps to reproduce

This should be a numbered list of the steps that you took in order to notice the problem. The person who opens the bug report will try these steps and if they can see what is wrong, they may fix the problem. But if they cannot, there is nothing they can do. This first step is called "replicating a bug" and the steps that you describe are vital to making sure that bugs can be replicated before being fixed. Check out the example below.

Steps to Reproduce are as follows:

  1. I log in to our site as a returning user.

  2. I add a pair of Nike Air VaporMax (color: dark sky blue) to my shopping cart.

  3. The cart shows a total of $155.

  4. I now add a Men's Windrunner jacket which costs $100.

  5. Now, I remove the Windrunner jacket from the shopping cart and the total shows up as $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

When you look at the step "I log into our site as a returning user", that might be a reasonable description. And when you say "I add a Mens' Windrunner jacket", that too might be ok.

But it's even better to use links, like in the following example.

Steps to Reproduce are as follows:

  1. I log into our US site and log in with username: buygreatstuff and password: logmein123

  2. I add a pair of Nike Air VaporMax (color: dark sky blue) to my shopping cart

  3. The cart shows a total of $155

  4. I now add a Men's Windrunner jacket which costs $100

  5. Now, I remove the Windrunner jacket from the shopping cart and the total shows up as $100

EXPECTED and ACTUAL Behavior

If you write two sections into your bug report, one for EXPECTED BEHAVIOR and one for ACTUAL BEHAVIOR, it again makes it much easier to understand. Let's look again at our steps to replicate with these two sections added!

Steps to Reproduce are as follows:

  1. I log into our US site and log in with username: buygreatstuff and password: logmein123

  2. I add a pair of Nike Air VaporMax (color dark sky blue) to my shopping cart

  3. The cart shows a total of $155

  4. I now add a Mens Windrunner jacket which costs $100

  5. Now I remove the Windrunner jacket

EXPECTED BEHAVIOR: The cart total shows up as $155 (I added shoes of $155 and jacket of $100 and then removed jacket)

ACTUAL BEHAVIOR: The cart total shows up as $100.

Use Screenshots

A screenshot is helpful because it shows:

  1. Proof that you saw this problem

  2. Where on the screen you are talking about 

You can use a tool that lets you put arrows and text into your screenshots also. When you annotate your screenshots in this way, it becomes very easy 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 product created by Atlassian (the makers of Confluence) and is the most popular bug tracking tool on the market (so it's good for you to know!).

Additional Resources

Example of certificate of achievement
Example of certificate of achievement