Beth Soderberg 11:41 am on June 7, 2016  

Troubleshooting Workshop Outline

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.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://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 CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. and HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites., and know at least some of the basic tags/attributes (like href, strong, etc)
  • Have a WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ username (can be new account, doesn’t need to be super active).
  • Have used FTPFTP FTP is an acronym for File Transfer Protocol which is a way of moving computer files from one computer to another via the Internet. You can use software, known as a FTP client, to upload files to a server for a WordPress website. https://codex.wordpress.org/FTP_Clients. before.

If you have any experience with SQL (phpMyAdmin is fine), SSHSSH Secure SHell - a protocol for securely connecting to a remote system in addition to or in place of a password., and/or manually installing WordPress, that’s a plus, but not required.

You do not not need to know PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. or JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. 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 installLocal Install A local install of WordPress is a way to create a staging environment by installing a LAMP or LEMP stack on your local computer. 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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, a theme, or somewhere in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.?
  • 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 URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org 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:

  1. Would these plans necessarily fit with our “format”? If no, is that a problem?
  2. 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?
  3. 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.
  4. 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?
  5. 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:

  1. 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?
  2. Go through and check the materials to make sure they are still accurate.
  3. Per the questions above, decide what format to present these materials in.
  4. Decide on an outline for the workshop, using the list of plans in this post as a jumping off point.
  5. 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!