Troubleshooting Handbook – Progress Update

TL;DR The Troubleshooting Handbook is off to a great start and trucking along, but is also in need of your help. Contributors welcome!

Why do we need a troubleshooting handbook?

Whether energized by a local WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. or driven by their own desire to help others, many volunteers come to the 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. Support Forums to show their WordPress love by giving back in the form of solving other’s issues.

However, giving support is not something that we are all born with; If anything it is a learned skill. A desire to help goes a long way, but what about the other things that go into giving good support, such as:

  • Helpful tools and strategies for troubleshooting WordPress sites
  • Exercises on how to break a site (and then fix it) to gain a firsthand understanding common issues seen in support
  • Advice on effective communication styles and approaches to use when helping others
  • Tips and trick for working with the forum software (as a volunteer rather than a moderator) to make life easier.

Currently, there is no go-to guide that collects all that information in one place for anyone starting out to benefit from; the Troubleshooting Handbook aims to fill this gap.

Where we are now

Work has finished on building the initial Handbook structure, as well as an import of content from Break/Fix (the inspiration for this project) which completes the first phase of this project.

Many sections of the handbook (See spreadsheet) have pages that are in various stages of completion, and could use help to get the rest of the way. Here is a breakdown of were we could use your help.

Section 1 – Getting started

Ideally, this section should read like a “quick start” guide to volunteering in the forums, but it’s too disjointed to function that way currently. You can help by expanding content on the following pages:

Section 2 – Break/fix lessons

This section is meant to be a hands-on set of exercises on how break a site, with info on how to troubleshoot and fix it. This relates to common issues seen in WordPress support.

Content in this section is fairly complete, owing to having been largely imported from but if you have an idea for an exercise you would like to contribute to expand this section or ideas on how to make the existing exercises better, let us know!

Section 3 – Giving good support

Most of the topics in Section 3 are without content, having only placeholder pages or article stubs. Feel free to check out any of the pages in this section to see if any interest you. They are all open to your contributions.

Also, props to MacManX for kicking off the pre-defined replies page:

Giving Credit

We have also added a credits page, which will expand over time, but for now reflects the hard work that has gotten us here so far. We’ve also including a shout-out to the original rockstar contributors to the Break/fix site this project derives it’s inspiration from. Check it out, and if you’d like to contribute, let us know in the comments.


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

Troubleshooting Support: Adding troubleshooting to the Support Handbook

Hi everyone. @jdembowski suggested at the last meeting that it would be a good thing to post some info about the idea I brought up, so more people can add their feedback. So, here’s my idea…

The Support Handbook is full of information about how to do the job of being a forum moderator—how to deal with spam, abuse, bozos, etc.—but there is not really anything to represent the other half of the equation: How to troubleshoot common issues once they get here.

While there is a page in the Codex that helps solve a lot of common issues that face users, there is still really nothing like it that is aimed squarely at troubleshooting from the perspective of a support giver, rather than a WordPress user.

Why we need a troubleshooting section

Naturally if you’re already a WordPress pro, you know how to do this stuff or can piece it together for yourself with an internet search. However, contributors arrive at the forums from a broad range of backgrounds, from power users to developers. The art of troubleshooting may not be second nature to them at all.

For experienced coder who is new to the finer points of WordPress, or perhaps a non-coder who has a strong desire to learn and help others (or anyone in-between really) adding a troubleshooting section to the Support Handbook can only help.

So where does this come from, thin air?

Not exactly. One place we could borrow content from to get us started is which is a site full of WordPress troubleshooting exercises that are hosted under @ipstenu‘s care, with many awesome peeps contributing to the content. The exercises themselves were developed to provide lesson materials for two workshops in 2013, which were well received, though the content not been developed since, nor any workshops taken place.

Something I like about the approach of the break/fix site (and related workshops) is that there are full downloads and example problems to work through. So it is an interactive way to learn troubleshooting by breaking—and then fixing—a test site, along with useful reference material on common tools and approaches for troubleshooting.

As far as other content that may work, there may also be relevant Codex content that can be pulled in and adapted, and I am sure new content/lessons could be added as well. So plenty of ways we could go here, though starting with a port of break/fix gets us off the ground quickly.

Sound crazy? Could it be better? Want to help out?

So this is just my idea for how we could expand the usefulness of the Support Handbook, and one that will benefit from as many viewpoints as possible. With that in mind, I’m really more curious to hear your thoughts on what would be the ideal way to approach adding troubleshooting info.

Please let me know in the comments. And if you want to help, *definitely* say something in the comments. 🙂