Getting web site errors fixed means telling your programmer or IT people what needs fixing, and it can be challenging to communicate effectively with them. Technical folks really want to fix things, and non-technical users really want them fixed. But the language each group uses to understand and describe the world is not quite the same. The resulting confusion is frustrating for both.
This post is intended as a guide for the non-technical users out there. It describes what techies look for and need in an error report. The more specific and accurate you can be, the more likely it is that your developer will be able to identify and fix things. The following suggestions will help you be accurate and specific in ways that will help developers fix problems quickly and accurately.
1. Report promptly
This will make all the following items much easier. It’s basically impossible to troubleshoot a problem you had last week and that you only kinda sorta remember.
2. Report one issue at a time
Even if you have accumulated a laundry list of problems, please report them individually. Whether you are using a bug tracking system or just emailing your developer, it’s a whole lot easier to manage error reports if they each report only a single problem. Then we we can close or comment on single issues or create and manage a single email thread. Not only does this make the process less frustrating, but problems are less likely to fall through the cracks, and it’s generally much easier to see and measure progress.
3. Provide a URL
Even if I know your site inside and out, it can be unclear where you are experiencing a problem. Please identify the precise page where it happened. It’s very easy to cut and paste the address from your web browser. A report like “we can no longer see the author's name in the author name column” is more or less impossible to work with because, in all likelihood, there are several places in the public or admin sides of the site where author names are displayed. If that description is accompanied by a web address, however, we know exactly where to start working on a solution.
4. What actually happened?
It's tough to interpret reports like "the search didn't work" or "the site was broken". A good report should describe what you expected to happen versus what actually occurred: "I tried to search for new articles but nothing comes up, and I know there are several new posts"; "When I submitted my credit card info on the checkout page, I just got a white screen". You will have to spend a little bit longer typing up this kind of report, but you will then be spared the inevitable request to explain what you mean in more detail.
5. When did it happen?
This is amazingly helpful, and the thing most often missing in error reports. Note the time that you had the problem, as precisely as possible (and with your time zone, if you aren't in the same city as your techs). Web access and error logs are generally chronological, and knowing what time you had problems makes tracking down helpful messages not just easier, but possible. And if the problem is that a web page failed to load at all, or gave some kind of HTTP error, then knowing the time -- even approximately -- might be the only way to figure out what happened.
6. What were you doing?
It’s always useful to know what you were doing when the error occurred. And again, not just in general. If you were searching, for example, what terms or options did you use? If you are logged into the site, what account were you using? What was the precise link you clicked that made the whole thing crash?
7. Describe your browser and operating system
Differences in software can sometimes make a huge difference in your experience of a site. It matters a lot if you are using Internet Explorer 6 on a Windows XP desktop or Firefox on an Android phone. Always make sure you identify the operating system and web browser you are using, especially if the problem is in how the pages display, or in how dynamic elements or forms behave on the screen.
8. Cut and paste
If there is an error message or if the problem is in the output on the screen, cut and paste the text into your error report. Tech folks always appreciate getting the precise error number and message. It might be utter gibberish to you, but error messages can often make a solution immediately obvious to someone who knows how to interpret them.
9. Screen shots are amazing
One shortcut to providing a lot of the foregoing information all at once is to provide a screen shot. Generally this will include the URL, assuming the menu bar is visible, and any error messages or problems in the display. It can be very helpful if you have the time and skills to annotate the screen shot with an arrow or two and some descriptive text: “this should be green”, “these fields shouldn’t be here”, and so on. (Here's a good guide about how to create screen shots in various operating systems.)
So the takeaway, here, is that your reports should be as detailed as possible. "My profile picture isn't showing up even though I tried to upload it three times about 1PM yesterday; there was no error message" is much preferable to "profile pix not working fix pls". Your tech people might sometimes seem to work magic with the site, but they can't magically understand the problems you need fixed. Good, thorough error reporting is essential to fast, efficient troubleshooting.