There is a common, though citation-less, expression that many developers are quite familiar with, and it goes something like this: 20 percent  of my time is spent writing the code, the other 80 percent is spent debugging it. Depending on where you look, I would argue that it varies widely, but the fact still stands: debugging is a major portion of the development process, and it doesn’t end when a site goes live, either.  

Oftentimes, this process is slowed, to the frustration of everyone involved, by a lack of information about the problem. So I implore you, dear reader, to take a few minutes to familiarize yourself with the following questions and the reasons why they are important to debugging a website. If you can answer any of these, your developer will be grateful and will likely be able to make the changes faster:

1. What’s the URL and what actions did you take?
   • Are there any other examples or counter-examples?
   • Will a screenshot help describe the issue?
2. What browser are you using to view the site?
   • Which operating system are you using?
   • Does the issue occur in another browser?
3. Is the error reproducible?
   • Does clearing your browser’s cache solve the issue?
   • Does the error occur on any other devices or outside the office?

What’s the URL and what actions did you take?

When informed of a bug, a developer’s first step is to recreate it. Though it might seem obvious to send a link to where the issue is, it’s surprising how often I get the following email:

[insert problem here] is wrong with the blog. Can you take a look at it ASAP?

This is really ambiguous. You might end up being more explicit in describing the location of the problem than that, but the fastest way for a developer to get to the problem is by linking right there. Please, at the very least, provide the URL.

Sometimes, the error doesn’t occur until you interact with the current page. If that’s the case, list the steps you took to surface the issue. This is necessary to reproduce the error (more on that in a bit).

Bonus Points: Provide other examples

If you want to win bonus points with your developer, provide links to similar pages that also exhibit this particular bug  or even one that isn’t showing it at all. By establishing a pattern, it becomes easier to identify where the issue lies and what the root cause might be.

DOUBLE Bonus Points: Take a screenshot

If the issue is visual, subtle or potentially confusing when written, provide a screenshot! Heck, even if it’s obvious, a screenshot won’t hurt. Annotations only make it better, too!

What browser are you using to view the site?

This question is probably the one I ask most often of clients when they report a problem. Especially for design-related issues, the number one culprit is the browser. Just saying “in IE” won’t cut it, either. The difference between versions of Internet Explorer are vast (perhaps innumerable) and primarily why developers ask this question.

Don’t believe me? Check out how different browsers (and versions of the same browser) render identical code:

While this example is (intentionally) extreme compared to a practical situation, it demonstrates that even within a browser type, there can exist significant difference in what is displayed on the screen.

There are two things you should report about the browser: its name and its version number. Getting at the version number of your browser is simple. On Windows, click “Help” on the menu bar of the browser, then click “About {Name of Browser}.” Similarly on OSX, click the name of the browser in the menu bar, and then click “About {Name of Browser}.” This will reveal a small pop-up or page in the browser with some information about it, including a version number. This number matters less for Firefox or Chrome (since they update “automagically”), but you should still provide it if you think the issue might be browser-dependent.

Bonus Points: Name that operating system (OS)

The OS is also an important component, especially for mobile devices; the browsers on older Android phones and all iOS devices only update with the OS. Getting at the OS version requires more effort, and is very different from OS to OS, but may provide insight into why a particular issue is occurring.

DOUBLE Bonus Points: Check another browser

Part of the QA process is browser testing. While there are differences between how the site is displayed, browser testing is meant to identify actual broken functionality. If you have another browser installed, check to see if you can recreate the issue in that browser as well. This will help determine if it’s strictly browser-related or if the problem is more universal.

Is the error reproducible?

Like I mentioned before, reproducing the bug is the first thing the developer attempts when an issue arises. Sometimes though, despite all this information, the developer still cannot recreate the error. What does this mean? There are two possibilities here.

The first, an error of miscommunication or missing details: the information provided does not actually reproduce the bug in a repeatable fashion. This one can be avoided by more explicit instructions on how to produce the error (with screenshots). Perhaps some contextual information prior to the first step is missing (e.g., the type of user logged in). Certain browser settings will also impact how the page is rendered. Were any of these settings changed recently?

The second and worst-case scenario: the error is unique to your PC, mobile device or network. These are very difficult to debug for obvious reasons but are not insurmountable. At this point, you will likely need to be on the phone (or screen sharing) with the developer to more quickly address the issue instead of continuing the email chain. If it still requires closer inspection, the developer may need to access your device directly, either physically or via remote access. The irony, however, is that the fix for these bugs is frustratingly simple (e.g., an accidentally toggled setting).

With patience, there will always be a solution, but the more reproducible the problem is, the easier it is to fix.

Bonus Points: Clear the browser’s cache

If you find yourself in one of the two situations above, a good practice is to clear your browser’s cache. The cache is a temporary storage that keeps copies of certain assets of the site on your computer so that when you visit the site again, your computer won’t need re-download them. While the cache is beneficial, many changes won’t always be downloaded as soon as they are made. If you are seeing something old or unexpected, try clearing your cache.

DOUBLE Bonus Points: Check another computer

Another quick way to see if the problem is unique to your device is … to test another device! This technique, called component isolation, will help nail down the source of the problem. There are also cases where software on your network prevent certain content to load for security reasons or language filters. Try accessing the content outside the office and see if the issue is happening still.

Putting it all together!

With all of this information, a developer will be able to quickly assess the situation and fix the bug rapidly.  how would that previous email look if these questions were addressed?

[insert problem here] appears to be wrong with the blog articles: www.example.com/blog/my-cat-videos. It’s only happening on articles with videos; I don’t see it on the ones without. I’m seeing it in IE9, Chrome and iPhone 4S.

The original email only indicated one thing: something related to the blog was wrong. This improved email now says it’s happening on the individual articles, occurs only on articles with video, is browser/device-independent and provides a direct link to an example.

Armed with information, a developer can quickly locate the issue and resolve it. Depending on the situation, certain details may not be required, but for a quicker turnaround, providing more information is always preferred. Trust me, your developer will thank you!

Featured photo by ThreeHeadedMonkey on Flickr. Used under the Creative Commons License