A User's Guide to Effective Bug Reporting

By Ashia Zawaduk on Nov. 9, 2015

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 http://www.mysite.com/admin
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 www.whatsmybrowser.org and share the resulting URL (it will look something like this: whatsmybrowser.org/b/GAXPW45) 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:

MacScreenshot

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

How do I take a partial screenshot?

Mac2

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?

PC1

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

How do I take a screenshot of a single window?

PC2

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. 

Additional Reading:

Looking for more great reads? The following related articles might be helpful. 

4 Things to Look For When Hiring a Web Application Developer

The Lift Way: Project Management for Websites and Web Projects

3, 2, 1, Launch! Why is it so hard to get a website off the ground?

If you’d like to get in touch, please email Thorren and let him know how we can help with your project or question. 

Want to grow with digital?