Troubleshooting: Doing It Right When Things Go Wrong

Oct 2022 Eric Phillips
← Back to blog

Troubleshooting is a process we go through to try to repair something that doesn't work the way we expect it to. When you connect to your Wi-Fi but your device says "No internet connection.", when your lawn mower engine won't start, or when your website is a mess of unstyled content then it's time to start troubleshooting.

 

We might not be able to troubleshoot every problem ourselves. The level of difficulty of a problem depends on the complexity of the system we're trying to repair, the knowledge, skills, and tools we have available, as well as the scope of any damage. But even if you can't fix something by yourself, following some basic troubleshooting steps will give you a greater understanding of the issue that you can use to give someone else a head-start.

 

The basic steps for troubleshooting a problem are:

  • Describe the problem
  • Reproduce the problem
  • Eliminate variables
  • Develop and test a fix
  • Ask for help

 

Describe the problem

Start by going Dragnet; "just the facts."

 

In our frustration it's tempting to be curt; "The engine doesn't start.", "The website is messed up.", "These seeds won't sprout". But really get down into the Who, When, Where, and What.

 

Establishing a timeline can be useful for identifying variables later, especially when you're troubleshooting something that used to be working. If something that was in a working state is now in a non-working state then something changed. Try to gather facts about what happened between the last time it was working and now. Or, if you're setting something up for the first time, describe the "happy path". In a perfect world, what are the series of steps that would happen if the system was working. Splitting up or flowcharting a process can narrow the focus to only those steps that are potential root causes of the issue.

 

One trick for describing problems is to think of the issue as a gap between what you expected to happen and what actually happened. Characterizing your problem this way might save you time later when you ask for help, especially if the people helping you aren't familiar with the thing that's giving you problems. Remember that most people aren’t mind readers and won’t know the history of an issue the way you do unless you repeat it to them.

 

Reproduce the problem

A key step to narrowing down causes is confirming that a problem is reproducible. Sometimes when we have a problem, it always happens. There are times when a website is down and it's down completely. But other times a problem is intermittent; it comes and goes. You refresh your browser and your website is there one minute and gone the next. This is a clue! Chronic and intermittent problems tend to have different causes and fixes.

 

Being able to describe the steps to reproduce a problem will also be key later on. The path you took to arrive at the issue reveals a lot about the variables involved. And perhaps more importantly, being able to tell someone else how to reproduce the problem gives them a huge boost when they try to help. If you describe the problem in detail with instructions for how to reproduce the problem, then they can basically skip directly to step three.

 

Eliminate variables

A related process to reproducing a problem is checking that it persists even as you eliminate variables.

 

An important point here is to start simple. Like the iconic scene in the movie Sling Blade; make sure it’s got gas in it. If your laptop's webcam stops working, confirm that it's actually on (it's all too easy to bump one of your function keys and turn it off). If the microwave won't start, double or even triple check that the appliance is really plugged in. If your website doesn't display the way you expect, flush your browser cache or use a private window to ensure you're really looking at the latest version.

 

A WordPress troubleshooting technique is to de-activate all your installed plugins and check if your site works, and then re-activate them one at a time until it breaks again. It's a systematic way to determine if one (or a combination) of your plugins is at fault. Another WordPress trick is to activate a default theme to eliminate (or confirm) faulty theme code as a cause. You might not always come away knowing exactly what the root cause is, but you'll know whether to focus on your theme, plugins, or your hosting environment.

 

Develop and test a fix

By now you might have an idea about what's causing the problem, and maybe even the means to try to fix it.

 

At this stage the most important thing is to be systematic and scientific. It's tempting to change many related variables all at once to try to fix a problem. But that's like throwing spaghetti at the wall just to see what sticks, and by the end you won't know if you got lucky or if you really understand what the root cause was.

 

Develop a hypothesis about the cause. Experiment by changing one variable. Test to see if the issue is still occuring. Troubleshooting isn’t just about fixing issues, it’s also about gaining knowledge of their cause.

 

Repeat until the issue is fixed (hooray!) or you run out of variables you can change. Now that you feel like you’re at the end of the rope you’re ready to proceed to the final troubleshooting step.

 

Ask for help

If you've gotten this far and still haven't managed to solve your issue, it's time to ask for help. My personal favorite guide on how to ask for help comes from StackOverflow whose whole gig is technical Q&A. If you’ve faithfully followed the steps up to this point then you’re almost perfectly prepared to follow their advice for technical question asking.

 

A general template for asking for troubleshooting help would go something like this:

 

Describe your problem in terms of what you expected to happen and what actually happened. Be specific about:

  • The steps you went through up until the moment you experienced the problem.
  • The steps you can use to reproduce the problem (or mention that the problem isn’t consistently reproducible)

Discuss what you tried changing to either eliminate variables or fix the problem. What did you change? What, if any, was the effect that it had?

 

And remember that often asking for help is the most important troubleshooting step.