mark l chaves

i'm from ohio. i feed stray dogs & cats.

WIP as of 17 February 2023.

Here’s a rough draft of steps to troubleshoot a website problem.

You might need to go back and repeat a step more than once. For example, you can be on step 3 and need to go back to step 1 to ask more questions and update the problem description.

The Steps

  1. Understand what the customer is asking. #
  2. If needed, sync your understanding of the problem with the customer.
  3. Reproduce the problem as soon as possible.
  4. Write down your educated guesses (hypotheses) about what’s causing the problem.
  5. Rule out your guesses until you find out which one is causing the problem.
  6. Test your fix or workaround.
  7. Write down what you’ve done so far.

Step 1) Understand what the customer is asking.

You should be able to describe the problem. Your problem description must include steps for reproducing the issue.

What the customer needs isn’t always what they say. You need a sixth sense to read between the lines and ask precise questions.

Skills you need:

  • Listening
  • Reading
  • Analyzing
  • Asking questions
  • Interpreting what the customer tells you (reading between the lines)

What we need to know:

  • Where is the problem happening
  • What’s happening
  • What should be happening
  • The steps to make the problem happen (reproduce the issue)
  • As many symptoms like errors and weirdness

Depending on what you know so far, do either step 2 or 3 next

Step 2) If needed, sync your understanding of the problem with the customer.

Step 3) Reproduce the problem as soon as possible.

Prerequisites:

  • Where the original problem is happening and how to reproduce it (stuff from step 1).
  • Access to a dev, test, or staging copy of the customer’s site.
  • Or, access to a site you can create a reprex of the issue.

Skills you need:

Step 4) Write down your educated guesses (hypotheses) about what’s causing the problem.

Step 5) Rule out your guesses until you find out which one is causing the problem.

By the end of this step, you might not know the exact root cause, but you are in an excellent place to test a fix or workaround.

Take this example: On all of the admin pages, we see a notification message that tells us to click a button, but we don’t see any.

  • Hypothesis 1: There’s a CSS conflict. The button element is there, but some CSS rule is blocking it.
  • Hypothesis 2: There’s a code conflict. Some 3rd-party code is clashing with the code that’s supposed to generate the HTML for the button element.
  • Hypothesis 3: There could be a bug in the code that’s supposed to display the button.

TO DO: narrowing down, pruning, and getting rid of things that don’t contribute

Step 6) Test your fix or workaround.

TO DO

Step 7) Write down what you’ve done so far.

TO DO

References

Credits

TO DO