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 P2 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 forum 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 core skills from different areas of the web, but are not familiar with WordPress 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 plugin 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 (DNS checkers, validators, etc.)
B – WordPress standards
- Don’t hack core and other core principals
- Editing CSS the right way – Child themes, not theme hacking
- GPL, 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.