How to report bugs to your web team

Clinton Reeves / Posted 1.17.2017

How to report bugs to your web team


Are website bugs frustrating? Absolutely! Bugs are frustrating for you, for your users, and even your developers. In fact, I’ve never met a developer who wants to send out buggy code. One way or another, our names and reputations are ultimately attached to our work—we have no desire to “ship” junk. I’m sure those types of developers exist (see How to tell if your developer is BSing you), but I don’t think they last very long in the industry. What I want you to take from this is that, when you encounter a bug on your website or a software application you’ve paid to have developed, your goals and the goals of your development team are normally in direct alignment—get the issue fixed as quickly as possible.

Ultimately, the process of fixing the bug is going to fall into the hands of your development team. But given that we all have the same objective when submitting a bug report, there are some very simple pieces of information that you can include to help us resolve it as quickly and efficiently as possible.

Components of a rock-solid bug report

Before we dive in, I do want to take a moment to point out that there are multiple types of software applications that we all use on a regular basis. At a high level, the components we discuss here will be relevant to all of these. That being said, the terminology and examples I use will be geared specifically towards websites and web applications.

Specifics are going to form the core foundation of a good, solid bug report. When describing an issue, try to be as detailed as possible. Whenever a bug is submitted, the first thing that a developer is going to do is attempt to recreate it and “prove” that it exists. As you can imagine, attempting to recreate an issue with minimal details can be an extremely time-consuming process. The more information you provide, the easier it’s going to be for them to figure out what the problem is and the most efficient way to fix it.

The following sections will outline additional pieces of information you can include to help with this process.

Location

Identifying the location of a bug on a website, or any system, is very important for the person who will ultimately be working on resolving the issue. This is universally applicable to systems of all types and sizes.

Identifying the location of a bug is actually a two-step process. For websites, the first location you will want to provide is the specific page where the error can be found. This is as simple as providing a link to the page in question. If you find that the issue is present on more than one, you don’t have to provide a link to all of them, but do let your developer know it’s happening in multiple locations so they’re aware.

After providing the page where the bug can be found, you’ll then want to identify where the issue is within the page. You can describe this however you would like; you don’t need to worry about being extremely technical. Your goal here is to help your developer jump straight to the problem quickly as possible. The examples below will help.

Avoid: One of the forms on our website isn’t working.

Getting Better: One of forms on the www.example.com/contact-us page isn’t working properly.

Excellent: The form on www/example.com/contact-us doesn't appear to be working properly. It's the one in the blue box on the right-hand side of the page, the second one from the top. 

Description of the issue

Once you’ve identified the location, the next step is to provide a description of the issue you’re having. In my experience, I’ve found that the best way to write a good description is to focus on two key points:

  1. What’s currently happening (the problem)
  2. What should be happening (what you expect to happen, without the problem)

This is your opportunity to tell your developer the story of what’s happening. It doesn’t need to be a lengthy explanation, but building off of the goal of “specifics,” the more detail you can provide, the better. At a minimum, try to give enough information to allow them to pinpoint the issue as you experienced it. Here are a few examples:

Avoid: When I submit the form, it displays an error.

Although technically correct, this isn’t very helpful. There can be lots of reasons for a form to display an error, and some of them may actually be valid. If you’re getting an error that seems incorrect, you’ll want to provide more information to help the developer hone in on it.

Excellent: One of our content editors recently told us about a weird error she received when testing the contact form on our site. I tried it out myself that day and everything worked just fine, but today, while I was entering a new blog entry, I tried it again and I got the same error. When submitted, this form should send an email to the selected Department/Division so they can contact the user, but that doesn’t seem to be happening.

This is much more helpful. Yes, it does require a couple of additional sentences, but to a developer, you’ve just provided 3 critical pieces of information that they can use to identify the problem.

Steps to recreate

The last helpful piece of information you’ll want to include in your bug report is a brief, step-by-step outline of what your developer can do to recreate the exact scenario you were in when you encountered the bug. This is actually a process many developers use when reporting a bug internally to one another. The reason we do this is because it eliminates guesswork and provides straightforward, precise information that will put us at the root of the problem as quickly as possible.

When building out these steps, your goal is to create a simple roadmap that will lead a developer straight to the bug you encountered. All you have to do here is just walk us through what you did when you initially encountered the bug, and break it down step by step.

Revisiting the example we’ve been working off of, let’s say the form in question looks like the following:

Based off of the description of the bug we provided above, our “Steps to recreate” might look something like:

This is what I did before encountering the error:

  • Logged in to the control panel of the content management system
  • Created a new entry in our blog
  • Remembered the error that was reported the other day, decided to test the contact form, and went to http://example.com/contact-us
  • Filled in form fields
    • Set “Name” field to “John”
    • Set “Phone” field to “111-111-1111”
    • Set “Email” field to “email@example.com”
    • Set “Division” dropdown to “Sales”
    • Entered “Testing—Hello World” into “Message” box
  • Submitted the form and the error was displayed

Pretty easy, right? Believe it or not, those 10 simple steps that took no more than a minute or two to jot down can very quickly shave off a decent amount of troubleshooting time for your developer. Of course, the less time they spend troubleshooting, the faster they can get to fixing the actual problem. Now, based off of the information you’ve already provided, is this a bit redundant? Yes, it most certainly can be. But often times, when you break things down like we did above, you inevitably include a few tiny details that weren’t mentioned in the description you provided, and sometimes those tiny details provide the source of—and the answer to—the problem at hand.

Additional information

The following are a few select pieces of information that, although helpful, may not always be practical or possible to include. My general recommendation is, if you can provide them, do it; if not, don’t worry about it. If you have already provided the core information outlined above, you have likely cut down the resolution timeframe substantially, and your developer can follow up with you to request the information below should they need it.

Screenshots

As the old saying goes, “A picture is worth a thousand words.” If you’re having trouble describing a bug, or just want to make sure your developer understands exactly what you’re talking about, include a screenshot to show them. This will take a little extra time, and may not always be feasible, but is highly recommended whenever possible.

Browser and version

In modern web development, a user's browser can create an entirely different set of results than one would expect. I’ve included this under the “Additional information” section because, depending on the issue at hand, it’s an important piece of information, but it’s not always relevant. I would encourage including it whenever possible. If you’re having trouble locating this information, http://www.whatsmybrowser.org/ will quickly provide you with the information you are looking for.

Wrapping it all up

We’ve covered quite a bit in this article. I have no doubt it took you a bit of time to read, as it took me a fair amount of time to write. While the overall process may seem more complex and/or time consuming than you might be accustomed to, if we strip out all of the additional commentary, the final bug report we would be sending to the developer would actually look similar to the following:

Hi Jane,

We seem to be having an issue on our website and we were hoping you could take a look and resolve it. I’ve provided specific details below:

Location:
The form on www.example.com/contact-us doesn’t appear to be working properly. It’s the one in the blue box on the 
right hand side of the page—the second one from the top.

The problem:
One of our content editors recently told us about a weird error she received when submitting the contact form on our site. I tried it out myself that day and everything worked just fine, but today, while I was entering a new blog entry, I tried it again and I got the same error she reported.

When submitted, this form should send an email to the selected Department/Division so they can contact the user, but that doesn’t seem to be happening.

Steps to recreate:

This is what I did before encountering the error:

  • Logged in to the control panel of the content management system
  • Created a new entry in our blog
  • Remembered the error that was reported the other day, decided to test the contact form, and went to http://example.com/contact-us
  • Filled in form fields
    • Set “Name” field to “John”
    • Set “Phone” field to “111-111-1111”
    • Set “Email” field to “email@example.com”
    • Set “Division” drop down to “Sales”
    • Entered “Testing—Hello World” into “Message” box
  • Submitted the form and the error was displayed

Thanks,
John

 

With this one straightforward and detailed message, you can very easily provide your developer with everything they need to know to review and resolve a bug on your site quickly, without needing to send multiple follow-up messages requesting additional information.

Clinton Reeves

Clinton Reeves

Back-end Developer

Clinton is a back-end developer at Q Digital Studio who lives and breathes code. He is Q Digital's resident problem-solver; if he can't fix it, he'll just create new code or a shiny new add-on. When he's not problem-solving at the studio, he's likely tinkering with an arduino project, or working on his house.