Learning to Troubleshoot WordPress

UPDATE 2/3/21: I now have a course on LinkedIN Learning that teaches troubleshooting for web developers.

I don’t care if you know a lot about WordPress or if you know only a little. It doesn’t matter. The important thing is that you can figure out how to get (and where to find) answers when you don’t know something.  That’s a far more powerful skill than just having knowledge.

I’ll share some resources in this post about troubleshooting (specifically for WordPress), but this isn’t about showing you all the ins and outs of those resources. It’s about giving you the confidence to figure things out even when you don’t know where to start. It’s about teaching you to fish, so to speak.

Troubleshooting has been my greatest teacher as a developer.

— Blithe Rocher (@Blithe) May 15, 2014

The slides and notes below are from my Learning to Troubleshoot WordPress presentation at WordCamp Orange County 2014.

Learning to Troubleshoot WordPress Slides

Troubleshooting 101

Starting with the Right Steps

If something on your WordPress site “doesn’t work,” the first step is to narrow down the source of the problem. Is it a plugin? Is it your theme? Use this flowchart to start:

Bonus tip: If you’re the admin of a multi-user site, use the Stream plugin to track and monitor user activity. You can easily see “who did what,” which is an invaluable troubleshooting tool when a problem “pops up out of nowhere.”

Fixing Common Problems

There’s an entire WordPress codex page dedicated to troubleshooting common problems in WordPress, such as permalinks not working, or pagination acting wonky.

Bookmark it and check it – you’re likely not the first person to experience whatever problem is in your way.

Additionally, just about every theme and plugin in the WordPress ecosystem has some form of documentation, even if it’s only in the form of well-documented code or user comments. If you’ve narrowed down a problem to a specific component, search at the source for the answer first.

Editing WordPress Files

Before we go further, we need to talk about editing WordPress files. When we talked about editing WordPress files, we really mean editing your theme, your child theme, or your custom plugin files. Never edit core WordPress files or public plugins – the next time you apply an update, you’ll lose your customizations. Don’t make the panda sad.

Syntax

Text Editor

Do yourself a favor and use a syntax-highlighting text editor. I currently use Sublime Text and have used Notepad++ in the past. Other popular text editors include Dreamweaver and Coda.

For a full-fledged IDE (integrated development environment), PHPstorm or NetBeans are popular options. While not technically an IDE, VIM is an interesting option.

Syntax Checkers

When one misplaced quote can send your world crashing down…

• HTML
• CSS
• PHP
• JavaScript

Style

In-Browser Tools

Quickly identify the CSS selectors you need to target a particular element and test changes directly in the browser.

• Firebug
• Chrome Developer Tools

Debugging

• Query Monitor – View debugging and performance information on database queries, hooks, conditionals, HTTP requests, redirects and more.
• Debug Bar – Adds a debug menu to the admin bar that shows query, cache, etc.

Speed & Performance

Browser Tools

• Pingdom Speed Test
• Google Pagespeed Insights
• WebPageTest

In-Depth Analysis

• Sitespeed.io (and a nice review from Mika Epstein)

Your Network

Don’t overlook your network when it comes to finding answers to questions. While there’s definitely something to be said for trying to figure something out on your own, don’t burn 4 hours on a problem when you have access to someone who can point you in the right direction. Give it a good try and then ask for help. (If you ask for help before you’ve bothered to Google it yourself, you’ll just annoy people, so it’s not cool to abuse your network.)

If you don’t know those people are who can point you in the right direction, then start investing in building your network. I use the word invest, because it takes time, energy, and effort to seek out and maintain relationships. You’ll need to be an active resource for others who aren’t as advanced for you (answering questions in support forums is an awesome way to do this) and add value for those around you. When you’re regularly engaged this way and generous with your time and knowledge, people will happily help you out when you need it.