jerrysarcastic 5:15 pm on May 23, 2014
Tags: troubleshooting ( 3 )

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 http://breakfix.elftest.net/ 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. 🙂

#troubleshooting

Josh Pollock 5:25 pm on May 23, 2014

I think this is a good idea and would love to help out. I am the community manager for Pods, which involves a lot of troubleshooting so I would be happy to help write up troubleshooting steps.

One thing I think might be useful for this is a list of steps for describing an issue in a tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. ticket that I created based on a discussion lead by Andrew Nacin and Mark Jaqutih at 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. Orlando 2013 contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/.:

https://gist.githubusercontent.com/Shelob9/7517200/raw/78a529a5b546a2ae84efd846171e8f0f3ffdc980/good-bug-report.txt
- jerrysarcastic 7:19 pm on May 27, 2014
  
  Hi Josh, that is a pretty good (and comprehensive) troubleshooting list and similar in many ways to how I approach user issues as well.
  
  I could see several of those expanded into a “Support Tools” section that talks about how to do things like use WP_DEBUG in a support context (this Codex page is written very much from a developer point of view, for example) or how you would go about talking a user how to find 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/. errors and report them back.
Mark (podz) 12:34 pm on May 27, 2014

I posted this earlier to the wp-forums mailing list. Worth adding into the project in some way?

Thinking about ways to help new contributors, help those searching and also highlight excellent answers I wondered if it would be useful to start tagging such replies.

For instance, someone posts a problem and Bill replies with a model answer. That answer is great for the user, great if you read it but otherwise lost? Tagging it gives a new contributor a way to read and gain more knowledge to help, it means as WP develops such replies can find their way to a handbook or other resource and maybe if search changes they could be flagged up as possible answers.

Another example. Someone posts but their problem is not well defined. The replies they get help define the issue, do not confuse the user and the result is a solved issue. Teasing out what the problem is can also be an issue and doing it well is a valuable skill.

Is this worth doing?

If you think so I am happy to compile a list of those tagged each week to post here. Could even make a weekly Information post to the forums also to raise the level of awareness of it.
- jerrysarcastic 7:08 pm on May 27, 2014
  
  Tagging it gives a new contributor a way to read and gain more knowledge to help, it means as WP develops such replies can find their way to a handbook or other resource and maybe if search changes they could be flagged up as possible answers.
  
  I think a way to tag these is a good place to start, as examples of *support done well* is a great way to learn. Would these tags be visible to users, as well as forum mods? How would they best be implemented you think?
  - Mark (podz) 1:33 pm on June 2, 2014
    
    I think tags should be visible to everyone. That way we can indicate to potential new helpers that these tags are good ones to subscribe to.
    
    However – from experience we then need to emphasize that it is crucial to actually read the ticket. I have in the past seen answers of mine and others pasted by someone trying to be helpful but the answer is not the right one for their issue. So the OP gets poor information and we have to then advise the replier that they did not read/understand the question fully.
  - Mark (podz) 1:35 pm on June 2, 2014
    
    Also, might it be useful to have a tag which asks for more help?
    
    I say this because if there is a thread you have helped with then it will not be in No-replies, others might glance at it and assume that as you are replying that all will be good. But what if you hit a dead end with your knowledge? How do we flag that up to get more eyes on it?
Jan Dembowski 1:37 pm on May 27, 2014

I really like the idea of incorporating examples like the ones in http://breakfix.elftest.net/ as well as highlighting great answers in the Support Handbook.

They’d be two separate sections so break fix would cover “Here is how it broke, how to determine that and here’s how you fix it” while Mark’s idea would be “This is why this is a great answer, kudos to Bill (insert link to answer)”.

Would it be a good idea to start examples of both in make/support and assign each a categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging.? Later on as the sections in the handbook develop they can be inserted into those areas.
Ipstenu (Mika Epstein) 2:35 pm on May 27, 2014

We could write fake questions that are common?

“I have this cool theme and I need to change the background color!”

Bad Answer: Just edit style.css!

Better Answer: You’ll want to edit the CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site..

Best Answer: You need to edit the CSS, and you can do this in two ways. Either use 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 that lets you override the CSS (like the CSS editor in Jetpack) or create a child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/.…
- Jan Dembowski 4:19 pm on May 27, 2014
  
  Fake questions are good especially as an example. That one happens all the time but occasionally there are questions about modifying 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’s output.
  
  If the plugin uses actions or filters (my favorite WordPress feature) then the answer could be good too as an example how the actions and filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. queuing works.
  
  I really like the idea of documenting those examples…
- Josh (WP Edit) 5:29 pm on May 27, 2014
  
  +1 Mika. Your solution seems to bring the best of both worlds.
- jerrysarcastic 7:35 pm on May 27, 2014
  
  We could write fake questions that are common?
  
  I like how this is also an example of how to answer 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. in mind.
  
  Beyond just example questions, is it worth having a section in the Handbook about “How we do things the WordPress way” as a reference for anyone helping out who is an experienced coder but may not really be aware of some of the long-held standards we have in the community?
- Mark (podz) 1:38 pm on June 2, 2014
  
  Love this idea.
  
  What about kicking it off with a post to the forums mailing list asking for those fake questions and the start of a worst / best reply? Then hone those and link them up within the handbook?
  - Jan Dembowski 2:29 pm on June 2, 2014
    
    I don’t think that would be a bad idea (a post in the forums) but the forums tend to have items like that scroll by and get lost.
    
    We could make it a sticky post but perhaps a post somewhere that gets visibility on the WordPress dashboard?
    
    *Jan makes loud coughing noises in the direction of @jeffr0 and @pollyplummer in a totally non-discrete way*
    
    Edit: Reading is fundamental on my part (meaning I almost never read correctly). An email to the wp-forums list is a good idea, 😉