Over many years of building and managing websites, I’ve seen a lot of errors, bugs and puzzling behavior. I’ve also received lots of calls for help when things go wrong, both from site owners and other concerned users. Unfortunately, most of these reports give me only a vague idea of what (if anything) is broken and how to go about fixing it.
Understand that I’m not trying to blame the messenger; fixing websites is my job. However, it would make my life a lot easier and get those websites fixed faster, if more people understood how to report a problem. Instead of emailing me to say, the site is broken, please fix it, start by answering these three questions:
- What were you doing?
- What did you expect to happen?
- What actually happened?
Veteran programmer Dave Winer explains:
All three parts are very important. If you really did discover a bug, the programmer will need to know what you were doing so he or she can try to reproduce it. If they can’t, it will be next to impossible to fix it.
The second part helps nail down the first part. Usually people know what they were expecting. Also, it’s possible that what you were expecting isn’t what the software does. An extreme example: “I was expecting that when I pressed the blue button at the bottom of the screen I would be granted three wishes.”
For the third part a screen shot can help. It may contain information that’s meaningful to the programmer that you wouldn’t think to include in your report.
In order to fix most problems, they must be reproducible. Quite often, people on the Internet experience glitches (a technical term) that come and go quickly, the causes of which will never be known. On the other hand, some bugs that are quite real occur only as part of a specific series of steps and can be maddening to track down. In most cases, more explanation is better. Be verbose. As programmer Simon Tatham says,
The first aim of a bug report is to let the programmer see the failure with their own eyes. If you can’t be with them to make it fail in front of them, give them detailed instructions so that they can make it fail for themselves.
Following these steps when reporting problems can be useful in other troubleshooting situations too. Your auto mechanic would be thrilled if you were to tell him, “I was trying to start my car and expected the engine to turn over. Instead, when I turned the key in the ignition, it just made a clicking sound.” You, my friend, are on your way to getting your car fixed.
So please, report website problems when you find them using the three step process. Your web developer will thank you and your website will be on its way to working properly again.