I have been spending quite a bit of time recently helping out with compatibility issues on sites such as StackOverflow and the MSDN forums. It is often difficult to give helpful advice, as the reporter doesn’t give sufficient details to debug the problem. Instead of repeatedly typing the same message in each thread, I’ve distilled some points here, that may guide you when reporting your web development woes. Taking some time to stop and think, and put yourself in the shoes of the person that will read your report, will help you create better reports, and you’ll receive faster and better quality feedback.
Avoid common issues
A few quick checks can spot the low hanging fruit that you may have overlooked:
- Check the error console of your browser’s developer tool. Especially if it is a JavaScript issue.
- Validate your HTML and CSS. Lint your JavaScript. It just takes a mismatched end tag, or missing semi-colon to wreak all sorts of havoc.
- Problem in IE? Check the F12 tool to make sure your page is using the latest document mode. IE can default to using an earlier version of the engine.
Sharing your problem
If you are still having issues, it is time to look for help. Follow the next few steps to improve your chances of getting helpful feedback.
Step 1: Give a way to run the code you are having problems with
If you don’t give people a way to run your code, it can be very difficult to find the issue you are experiencing. An inline code snippet in the post often doesn’t help, as the issue may not even relate to that code, and it is not possible to experiment with the code to try out different theories.
At worst case, link to the actual page you are developing. If you really want to be helpful, make a reduced test case, which only includes the minimum amount of code that still exhibits the problem. For example, if the issue is with your login form, you can probably remove all the HTML around it and the CSS that doesn’t apply.
There are a number of online tools such as JSFiddle that allow you to host small snippets of code. If possible use one of these. This allows us to edit the code and link back to the result. Popular tools include:
Step 2: Concisely explain the issue you are having
No need to tell a story about what you ate for breakfast. Include the following details:
- Short description of the issue. Keep it as short as a tweet if possible
- Steps to reproduce the issue. Even if obvious to you
- Result you are expecting
- Actual result you are seeing
- A screenshot if the issue is visual
- The browser(s), version(s), and operating system (if applicable) where you’re seeing the issue
- Any other essential supporting information
Step 3: There is no step 3
Sit back, relax, and wait for a reply. If you work out the issue before anyone replies, report back your findings. It saves someone wasting their time dealing with your issue, and will help anyone else that runs into the same problem as you.
Stumbled across a browser bug?
Often it isn’t your fault. It’s the browser. If this is the case, remember to report the bug with the browser vendor(s) in question. If they don’t know about the bug, they can’t fix it. Luckily, if you followed the steps above, most of the work has already been done, and you can copy and paste your excellent report into the bug tracking system of the browser vendor in question. But, remember to search first to see if the same issue has been reported.
Lea Verou has an excellent article on how to report browser bugs.
Here are the location of the bug trackers:
- Internet Explorer
- Opera (Note: Opera will soon be switching to WebKit)
- Firefox
- WebKit (Chrome and Safari)
- V8, for issues with JS support in Chrome