It’s just a fact of website life. Sometimes things don’t work the way they’re supposed to. Websites are the same. I’ve been on both ends of a broken website. I’ve had plugins and themes ((Even WordPress, on occasion, has bugs.)) that didn’t work for me, and I’ve built themes and plugins that didn’t work for others.
When you find yourself running into a problem, or “bug,” how you report it makes a huge difference in the time and effort required to find a resolution. I’ve helped many people in the WordPress.org Support Forums, and I’ve personally observed that the more specific a “bug report,” the bug reporter receives more and better help.
Here are my tips for reporting a bug to get a good response.
Tip #1: Stay Calm. Be Nice.
When you find a broken feature, especially if you’ve launched your website already, it’s easy to panic. That won’t get you anywhere. People are much more pleasant to work with when they’re not “freaking out” (I know. Duh!), so people will be more likely to help you if you stay calm. Even better, you’ll communicate with much more clarity.
Tip #2: Make Sure It’s a Bug
This is possibly the least-pleasant step, but it can save you time and embarrassment.
First, go back and double-check your work:
- Reread any documentation about the feature giving you trouble.
- Review any relevant settings.
- Try to recreate the bug in a different context.
- Closely read any error messages. They may explain how to fix the problem yourself.
It’s easy to blame others when something is going wrong. I know I have. Rule yourself out first.
Tip #3: See If Others Have the Problem
I use Google for this one.
- If you’ve got an error message, search for that.
- If the problem is with a plugin or theme, include that name in your search.
- If all else fails, try describing your problem as specifically as you can. Try it multiple times. You never know what other terms people have used.
If you find a bug report for your problem, you’ll be more helpful by leaving a message on the forum or sending an email confirming the bug and adding any additional details you think are relevant.
Tip #4: Report the Bug in the Right Place
If you know the person who’s helping you and you’re writing them an email, skip this point.
There are hundreds of support forums. WordPress.org has multiple forums for different topics. Plugin and theme developers maintain their own forums. Other websites like StackExchange and even my local WordPress meetup have great support forums. Make sure to find one that is appropriate. Once you do, read the forum guidelines to post in a way that won’t violate that forum’s standards.
It’s unfortunate, but I’ve seen a lot of really mean responses to people who post in the wrong forum, so be forewarned. ((Although why people are mean in support forums really boggles my mind.))
Tip#5: Write a Thorough Bug Report
So here we are. Tip #5. Finally! The bug report! Here are the parts of a good bug report:
Overview
Keep this brief, but it is good to kick things off with a short summary of what’s going on. Try not to speculate too much to the cause.
The Environment
Here, the “environment” means the bigger system of software where the bug is recurring. I’m going to use WordPress for this example, but you can probably imagine how this applies to other software. This includes:
- The browser version you’re using. (e.g. Internet Explorer 9.)
- You can usually find this under your browsers “Help” menu in “About.”
- Your WordPress version.
- The theme and other plugins you’re using.
- Any relevant settings.
Observed & Expected Behavior
This is probably the most important part and what people often leave out. It may overlap with the overview a bit, but being explicit here is worth it. Use specific language like “The red button in the upper-right corner and above the sidebar of the ‘About Us’ page on example.com/about.”
Observed behavior is bug you’re seeking help with. This often is in the form of “When I do X, Y does[n’t] happen.”
Expected behavior is what you thought would happen. “I thought when I modified setting A, I would see B.”
Anything Else?
Like I said, it’s dangerous to guess about the cause of a problem–it can send a good Samaritan down the wrong path–but if you notice that modifying something resolves the problem or you remember what you were doing just before the problem arose, include that information. It’s possibly to report too much information, but that’s a rarity. Most people report too little.
Bug Report Template
Here’s a template you can copy and paste directly into a support forum message to remind you of each step:
Description of the Problem:
Versions & Environment:
Observed Behavior:
Expected Behavior:
Additional Information:
Good Will = Good Help
If you’re reporting this on an online forum or sending an email to someone you’re not paying, showing that you’ve done due diligence in reporting this bug goes a long way. Even if you are paying for that support, doing the work up front to provide a clear bug report will get you faster and more pleasant support.
When I’m looking to help people on the WordPress.org forums, I rarely respond to postings if I have to ask for more information just to understand the problem.
Talk Back
If you’ve submitted a successful bug report, what made it successful?
If you respond to bug reports, what makes a good–or bad–report stand out?