• 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 9/9/24

Write a Good Bug Report

 

Discover 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."

A picture of a hand-written report with an insect (a bug) squashed on it.
Grace Hopper's first bug report

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 assurancewhose 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 need to 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 submit button on the quiz is activated."

  • "The monthly revenue report is wrong."

Ask yourself: "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:

  1. Easy to understand.

  2. 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.

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

  4. 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 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

  1. Steps to reproduce

  2. Device and OS

  3. Links

  4. Expected behavior

  5. Actual behavior

  6. Screenshots

Let's look at each of these in detail.

Include Steps to Reproduce

This should be a numbered list of the steps that you took when you noticed 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.

Imagine a bug where the quiz could be submitted without the last question being answered. The submit button would then be activated when an answer was missing.

The steps to replicating this bug are:

  1. Log into OpenClassrooms website. 

  2. Go to the quiz page of the course entitled "Understanding the role of product manager".

  3. Answer all questions except the last one

  4. Note that the submit button is activated

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 OpenClassrooms website" and "Answer all quiz questions except the last one " may be reasonable descriptions. However, it's even better to use links to make sure that everyone has access to the items.

In your steps to replicate this would look like:

  1. Log into the OpenClassrooms website with the username: OC and password: logmein123.

  2. Go to the quiz page of the course entitled "Understanding the role of product manager". 

  3. Answer all questions except the last one.

  4. Note that the submit button is activated.

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 be to 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:

  1. Log into the OpenClassrooms website with the username: OC and password: logmein123.

  2. Go to the quiz page of the course entitled "Understanding the role of product manager".

  3. Answer all questions except the last one.

  4. Note that the submit button is activated.

Expected behavior: the submit button should be disabled and nothing should happen when it is clicked. 

Actual behavior: The submit button is activated and we can click on it.

Include Screenshots in a Bug Report

A screenshot is helpful because it shows:

  1. Proof that you saw the problem.

  2. 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.

In the next chapter, 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!). Follow it carefully, because you’ll get a chance to create your own bug report at the end of the next chapter!

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).  

  • 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 to report and track them, in the next chapter!

Ever considered an OpenClassrooms diploma?
  • Up to 100% of your training program funded
  • Flexible start date
  • Career-focused projects
  • Individual mentoring
Find the training program and funding option that suits you best
Example of certificate of achievement
Example of certificate of achievement