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 https://make.wordpress.org/. 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 WordPress.org Plugin Directory https://wordpress.org/plugins/ 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. wordpress.org uses the actual IP address 198.143.164.252). 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 https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. 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

Handbook, Pass One

Okay, I removed all the pages that I knew were 100% .com

I left the pages that are maybe .com

What I’d like to see as a first pass is if people can, in the comments, rewrite them (in sections if you want) to correct them for the Codex. Once we have the info ‘right’, or right enough, we can do something like https://codex.wordpress.org/Handbook (I just stubbed it out to ‘save’ it) – Note: I do not know 100% if we’re going to stay ‘here’ or go to the codex with this, but either way, the principle’s the same.

We will need a ‘table of contents’ so if you have an idea, I’d really love to see this done like a book, and I want to aim it so that the new user (think about your most un-technical family member) sees the stuff at the top, and then follow things down logically. Check out https://make.wordpress.org/core/handbook/ for an example of what @hanni and I did there. It starts with learning, goes to contributing, and so on. Obviously this isn’t the exact same flow, but you see the idea.

It’s possible we’re going to end up with Handbook, Handbook/Themes, Handbook/Plugins, and then send ’em to CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress./Handbook for Handbook/Core. I’m 99% sure I can redirect a codex page to any 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. in mediawiki, but I may need to harangue Otto about that. We can decide how later on.

So our todo!

Then? We tackle that main codex page (once we know what info we want, we can organize how to coerce people that way). I’m not terribly worried about changes we don’t like, since MediaWiki has awesome revisioning.

Let’s get started!

The Handbook

On this post, let’s comment to get the BIG sections first. My spur of the moment ToC is this:

  • About WordPress – I know nothing, what is this thing.
  • Installing – How do I do that?
  • Settings (maybe ‘Configuring’?) – How do I make it look more me-ish
  • Just Write – Forget all this! I wanna blog!
  • Customizing – Themes and plugins and widgets, oh my!
  • Miscellaneous – The rest of the stuff 😉

Open for improvements. We can either ‘edit’ the pages in comments, or if you want to be an editor and be able to, er, editor the pages, speak up. Top level table of contents, let’s fight out here in the comments. Sub-page organization is going to be a nightmare no matter how we do it.

#handbook