Troubleshooting Support

Recap : Troubleshooting is a Handbook now!

Since bringing up the idea of having some sort of WordPress troubleshooting guide, we have discussed on IRC and P2P2 P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at some ideas for what to include, as well as where it would live. As for “where” it was decided quickly that this is best suited as a standalone handbook, rather than a part of the existing Support Handbook (aimed at forum mods) or the User Manual which is out of date and in need of some rethinking.

So we know where, now let’s talk a bit more about the other W’s (namely who, what, and when) of this new Troubleshooting Handbook.

Who it’s for: Newly arrived support forumSupport Forum WordPress Support Forums is a place to go for help and conversations around using WordPress. Also the place to go to report issues that are caused by errors with the WordPress code and implementations. volunteers

They’re not WordPress rockstars or Moderator material yet but instead a someone who has arrived at the the forums with a real desire to help. Awesome! The problem is that not all of us were born to be support experts, despite our drive to help others.

So this handbook would be aimed at:

  • Web developers who have coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. skills from different areas of the web, but are not familiar with WordPress coding standardsWordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook. May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards..
  • Power-users and non-coders who just want to help where they can, or are just trying to up their support game

What does it include: A starter ToC

Based on some of the feedback, as well as the original proposal to leverage the Break/Fix website to get us started, the following ToC sound like a good place to start:

01 Introduction – Basics of troubleshooting WordPress

Like a quick start guide, this would expand on the idea of having a troubleshooting checklist or flowchart for common issues with WordPress sites. Here is a good example of one to get us started, but I can see the possibility for more than one, perhaps focused on domain issues, server config problems, faulty themes/plugins, etc.

02 Hands-on lessons – Common hacks and breaks, and how to fix them

This would be the bulk of the handbook, and starting out would be populated with content from the examples and exercises sections of the Break/Fix site. These would each be created as sub-pages, and could be expanded over time to include other examples of WordPress breaky-ness and how to fix.

As a reminder, this content was created for a series of workshops, and I think it would be cool to keep the hand’s on feel of these exercises, including 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 Plugin Directory or can be cost-based plugin from a third-party downloads, source code, etc. This would also open up the possibility of re-adapting these back into workshops (at meetups and WordCamps) which would also be cool.

03 Giving Support – How to communicate with and help others effectively

This section would talk more about the other half of the support equation, and that is about communicating and managing the person asking for help, as well as “helping them help you” so to speak.

Of all the sections, this is probably the least defined ATM. One route might be to find a way of promoting examples of “support done right” taken from our existing threads—through moderator tagging perhaps? Another idea is to make this more of a “Goofus and Gallant” (#) style guide of what bad support and good support looks like.

I think there is a lot to be discussed here about what and how to implement this concept, so I’d be curious to hear your thoughts on this important section.

04 – Appendix – Tools and references for troubleshooting

The basic idea here it to have this be a place to collect some of the things that are really useful to anyone who is taking on a support-giver role. Sub-pages could cover the following topics (taken from Break/Fix) along with your suggestions.

A – Tools & Techniques

  • Local installs (MAMP, WAMP, etc.)
  • Using WP_DEBUG
  • Setting up a test site
  • Creating a phpinfo page
  • Browser and OS tools/extensions (expanded from here)
  • Online tools (DNSDNS DNS is an acronym for Domain Name System - how you assign a human readable address to a website’s exact numeric coded location (ie. uses the actual IP address checkers, validators, etc.)

B – WordPress standards

  • Don’t hack core and other core principals
  • Editing CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. the right way – Child themes, not theme hacking
  • GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing The GPL is a ‘copyleft’ license This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples., OSS, and other community minded standards.

When should we do this thing?

We have some great starter content on the Break/Fix site to get us started, so naturally, once we have a ToC we can be proud of, I’d like to propose getting a spreadsheet set up (to track progress and keep organized) and start with a port of that content. So, the short answer is, um, now! 🙂

Want to help? Have an idea? Let’s hang out!

Nothing great is ever accomplished alone, so if you are interested in joining in, or have an idea we haven’t thought of, please speak up in the comments. This would be a great project for anyone who is looking to contribute, but not a coder. Get off the fence and join us! 🙂

You can also swing by our weekly team chat (Thursdays at 16:00 UTC) in #wordpress-sfd IRC on Freenode.

#handbook, #troubleshooting