A User's Guide to Effective Bug Reporting

November 9, 2015
A User's Guide to Effective Bug Reporting

Whether immediately after launch or after several months or years of use, every web project has bugs that surface. These can be frustrating, both for the client and for the developer. Usually the frustration is not because of complexity, but as a result of communication challenges and gaps in understanding.

Clients generally understand that the purpose of a bug report is to alert us of a potential program error, however a valuable bug report takes that a step further and provides useful information in an efficient way. Writing a clear bug report doesn't have to be complicated and can go a long way to reducing the frustration. We've outlined a few key steps to help users create informative and detailed bug reports.

3 Steps to Bug Reporting

To help us get started, we ask our clients to respond to these 3 key questions when reporting bugs

1. What did you do?  

The goal of this section is to show the developer how to reproduce the bug. Keep it concise and easy to read.

Example: I went to
I entered in my username and password in the form.

2. What did you expect to happen?

Now that you have described how to reproduce the bug, you need to explain the desired result.

Example: I expected to be logged in to the admin interface

3. What actually happened?

Explain what actually happened as a result of the performed steps.

Example: I got a message that my login is incorrect, but I know I entered it properly.

Additional Context

Along with the description of the steps that lead to the bug encounter, it's also helpful to include evidence of the results you saw. Reproducing bugs can sometimes be a challenge, so capturing and providing added information is helpful for us in identifying the problem.

Some bugs may be related to the browser, and so it's key we have the browser information. A helpful link is to visit and share the resulting URL (it will look something like this: with us.

Screenshots are also incredibly helpful to attach, if you're unsure how to provide a screenshot, you can simply follow a few keyboard shortcuts:

How to take a screenshot on a Mac:

Your Mac captures the entire screen and saves it as a file on the desktop.

How do I take a partial screenshot?

Use your mouse to draw a rectangle in order to specify what to capture – or press the spacebar and then click on something (e.g. a window) to capture it. Your Mac then saves it as a file on the desktop.

How to take a screenshot in Windows?

Windows captures the entire screen and copies it to the (invisible) clipboard.

How do I take a screenshot of a single window?

Windows captures only the currently active window and copies it to the clipboard.

Make the Internet Better

Capturing and fixing bugs is important. By working together efficiently we can avoid some of the frustration that bugs can lead to and together make the internet better one website at a time.

Scott Barkman
Web Developer with development experience ranging from static single paged sites to full fledged web applications.
No items found.