There was a troubleshooting workshop that was put together years ago by some awesome people in the community. In March, I reached out to @ipstenu, who shared the troubleshooting resources from the workshop held years ago. They are located at breakfix.elftest.net and we have permission to use the materials and reformulate them for our lesson plans. Per the group’s initial conversations about this subject, we thought the first step to adapt these lessons for the training team is to inventory what is there and make a list of lessons that could be made out of it and then piece together what needs to happen from there.
The original workshop that was conducted using these resources is described here: https://learn.wordpress.org/workshops/. The original workshop included the following description for potential students to make sure that folks with the skills to make use of the workshop material were the ones who attended the workshop:
For this course to make sense, students need to have the following experience:
- Currently the admin of at least one self-hosted WordPress site (i.e., not on WordPress.com), with access to your hosting account and domain registration.
- Know how to edit settings, manage widgets and menus, update WordPress/themes/plugins, add themes/plugins — in other words, you manage a site vs. just creating content on a site managed by someone else.
- Able to recognize CSS and HTML, and know at least some of the basic tags/attributes (like href, strong, etc)
- Have a WordPress.org username (can be new account, doesn’t need to be super active).
- Have used FTP before.
If you have any experience with SQL (phpMyAdmin is fine), SSH, and/or manually installing WordPress, that’s a plus, but not required.
You do not not need to know PHP or JavaScript for this workshop.
I went through the whole website that @ipstenu created and have created a basic list of what resources are there and what we already have that could fit together in a workshop. A significant amount of the content on the breakfix.elftest.net site is actually individual troubleshooting exercises, so I went back to my notes from the inaugural workshop (which coincidentally I attended and thankfully still have the notes from!) to fill in some other pieces in this outline.
All of these exercises need to be done on a local install as they are dangerous to do on the real internet. We already have a lesson plan for local installs (yay!) BUT we could take a look at the breakfix version and see if there is anything from it that would be helpful to pull. In terms of lessons I outlined titles and relevant pages from the website or just bullets from my notes/thoughts.
Troubleshooting Basics
Local Install
- breakfix.elftest.net/tutorial/mamp/
- https://make.wordpress.org/training/handbook/theme-school/local-install/
Backing up Your WP Site
- https://make.wordpress.org/training/handbook/user-lessons/backing-up-your-wordpress-site/
How to Create a phpinfo() Page for Debugging
- include material from http://breakfix.elftest.net/tutorial/how-to-create-a-phpinfo-page/ and http://breakfix.elftest.net/tutorial/output-buffering/
Basic Troubleshooting Process
- Where is the problem? Is it in a plugin, a theme, or somewhere in core?
- What is the full error message?
- If plugin or theme is from the rep/download it and look at the code to see if it matches the code on your site. https://wordpress.org/plugins and wordpress.org/themes.
- Look at the error and the file, see if things match.
- How to report a problem in the forums
Exercises: Debugging Theme and Plugin Issues
Fixing a Broken Theme with Syntax Error
- breakfix.elftest.net/exercise/syntax-error/
Fixing a Theme Where CSS Changes Are Not Visible
- clearing browser cache
Debugging Basic CSS Problems in Themes
- I didn’t have a lot of notes from this part of the workshop, but I remember it being something where we looked at specific problems in themes and then talked through how to inspect and solve each problem.
Recovering from the White Screen of Death
- turn off all plugins & bring back one by one
- switch to default theme
- use a maintenance mode plugin
Recovering from Changing the URL of the Site
- change site URL via PHPMyAdmin, clear cache
Recovering from a Plugin that Triggers a Fatal Error on Activation
- http://breakfix.elftest.net/exercise/footer-fatal-error2/
Fixing Plugin with Headers Already Sent Error on Activation
- http://breakfix.elftest.net/exercise/headers-already-sent2/
- http://breakfix.elftest.net/exercise/headers-already-sent/
Debugging a Fatal Error when Plugin is Activated and Theme is Switched
- http://breakfix.elftest.net/exercise/fatal-error/
Reviewing and Fixing an Intentionally Vulnerable Plugin
- review: http://breakfix.elftest.net/example/review-a-plugin/
- fix: http://breakfix.elftest.net/example/fix-intentionally-vulnerable-plugin/
Exercises: Debugging Hacks
Debugging an .htaccess Redirect Hack
- http://breakfix.elftest.net/exercise/hacked-htaccess/
- http://breakfix.elftest.net/example/htaccess-redirect-hacks/
Debugging a Plugin that Automatically Changes User Passwords
- http://breakfix.elftest.net/exercise/changed-password/
Debugging a Hacked Site that Redirects Non-Logged In Users Elsewhere
- http://breakfix.elftest.net/exercise/hacked-site/
This outline is fairly comprehensive for an initial outline of such a workshop, but begs a few questions that were raised by folks on the team in our meeting last week (thanks @melindahelt and @chanthaboune!), namely:
- Would these plans necessarily fit with our “format”? If no, is that a problem?
- We had the format that we did so that each item could be modular. Can this material be approached in a modular fashion, or do you need to go in order to build on the skill set?
- How do we break up these materials into lesson plans? I’m in favor of keeping the individual exercises as their own little plans and having some more general plans that cover the other things.
- Would it be possible to leave these materials intact, for the most part, and flag sections that can be used as parts of other training workshops?
- Is the idea still to write this in a way that “anyone” can pick it up and teach it (like we did with other LPs) or do you need more of a technical background to be able to make sense of it and more importantly, answer questions?
Next steps on this set of lessons are as follows:
- Gather feedback from the group. What do we think of all of this? Are there more considerations we haven’t thought of that should influence how we structure this?
- Go through and check the materials to make sure they are still accurate.
- Per the questions above, decide what format to present these materials in.
- Decide on an outline for the workshop, using the list of plans in this post as a jumping off point.
- Write lesson plans for anything that is included in the outline, but that we don’t have written materials for.
Please add your thoughts/comments/feedback/etc. in the comments. All of this will be incredibly valuable as we move forward with making our first troubleshooting workshop!