Ideas for Docs and Support from the Open Help Conference

I’ve been at the Open Help conference in Cincinnati all weekend. Below are some of the ideas that I thought could have a particular impact on WordPress. I also took notes on all of the talks on my blog, there’s links to those at the end.

Jerry, Ryan, Mike, and Maria – feel free to add any of your own suggestions in the comments.

Indexing support forums

A lot of our support traffic is from Google, so people are searching for issues and then landing on the support forums. However, they are often landing on results that are completely out of date. For example, if you search for “WordPress permalinks not working” there are search results from three years ago and fix years ago. If you search for “WordPress 403 forbidden” pulls up results from 4 years ago. Should we prevent Google from crawling forums results over a certain age in order to help these searchers more easily find the content that they need?

Stack Exchange

How can we better support the work that goes on over on WordPress Stack Exchange? Should we get the moderators there more involved with the Support/Docs team? Should be look at ways that we can direct our more technical users & developers to Stack Exchange which they might find more suited to their needs?

User Advocacy

Should we have people on the support team act as user advocates and be more actively involved with WordPress development? WordPress is a user-focused product but there is little interaction between the development process and the support team. User advocates could act as a bridge between the developers and users. They could have responsibility for opening tickets based on feedback in the support forums, attend development meetings to raise questions from the perspective of users, and generally get involved with coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

Best Practices for Plugins

Mozilla has Project Squeaky to improve user experience for add-ons. They actively work with developers to ensure that users have a good experience. Many issues with WordPress come from third-party plugins – is there a way that we can help developers make plugins better? Some suggestions are best practices for 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 developers, a better plugin developer handbook, code templates that people can use for their plugins.

Better Integration Between Support Methods

Can we improve integration between the support forums and documentation? Could we suggest documentation pages based on the question that someone asks? Can we use apps like text expander or Alfred to create responses with links, best practice, and good suggestions, that forum moderators can use to help them deal more efficiently with support requests?

Analytics and Optimization

We should do some advanced analytics to find out what users are doing with documentation, how they’re finding it, what they’re clicking on. It would also be useful to do some user testings for common things that users are doing with WordPress: for example, finding and installing a WordPress theme, searching for plugins on the internet, finding documentation. Our users aren’t only users while they’re in the WP admin or even 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. What are they doing on Google? Where are they going for support? User testing can also be carried out to see how effective our documentation is.

Support for different versions of WordPress

There is a lot of information in the Codex relating to different versions of WordPress – some go back as early as WordPress 1.5. It makes no sense to have these in the Codex any more. We should also adjust the terminology for user documentation when new features are introduced the Codex says things like “Post formats is a theme feature since version 3.1“. While this is appropriate for APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. documentation, it makes no sense for user docs. Our documentation should reflect the current version of WordPress only.


#ideas, #open-help

I had a chat this afternoon with Lee…

I had a chat this afternoon with Lee Hunter who is the Drupal Docs lead. Documentation can be a lonely affair, and I think that connecting with other OS projects to share ideas and best practices is great for everyone. I’m hoping to do more of this in the future.

I thought I’d share some of the ideas that we discussed. These are certainly some things I’d like to see implemented/thought about once we get some of the current projects out of the way.

Content Stores

At the last docs chat, the issue of the coding standards was raised. At the minute they exist in two places. Centralised content stores may be the way to go to enable us to reuse content across the documentation. I imagine that we would have the document in one place and then use a shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site. to make it appear somewhere else.

There are issues that will arise out of this. An example is say someone arrives from Google on the CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. Coding standards page in the CCH, but actually they need to be in the theme dev handbook. We need some way of displaying where else the content appears so that they can get to where they need to be.

Document RevisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision.

Drupal has the Conditional Text Module which they can use to filterFilter Filters are one of the two types of 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. content according to a specific version. This means that they can support different Drupal versions in the documentation.

I guess this raises discussions about whether we actually want to support previous versions of WordPress within the documentation. After all, we want to keep people updated.

One thought that did come to mind is that Drupal uses tagging to tag specific pieces of text for different versions. In a WordPress context, I can imagine this being useful to display what appeared in different versions. Can we use taxonomies within the actual content as opposed to on the whole page? That might be quite interesting.

Documentation Tracking

Drupal has an issues tracker for Documentation which is something I’d love to see on It would be very useful for people to register an issue and for people to be able to see what issues there are an fix them. By keeping track of them in this way be could also organise doc sprints every 6 months to clean up any issues.

They also have a new contributor tasks list which would be useful for us on docs, as well as on coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. .

Another thing that Lee is trying to implement is to allow people to favourite pages. This will let people own a specific page, and receive notifications for changes made to that page. He also mentioned an “Adopt a Page” scheme, in which people own one specific page. I would love to see that. If every WordPress contributor owned just one page we’d have beautiful docs all the time. Once we’re further down the line in terms of building our new docs sections this would be something cool to implement.

Interactive walkthroughs

This is something very exciting which could have a big effect on tutorials and training. A Drupal developer is using the built-in Drupal tour functionality and Selenium to build interactive tutorials. His website is and he’s running an indiegogo campaign to fund it. The module he’s developing will walk people through complex forms, processes and configs one step at a time. Users are taken through the process, and can make comments on it. In WordPress terms, we could, for example, take someone through the process of setting up their website, or teach them to create content, or manage their multisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core. network. The possibilities are pretty exciting and I wonder if this is something we could think about for WP in the future.

Okay, that’s all of the ideas. I wanted to get them down to gauge interest and see if they are things that we would like to think about in the future. And to see if any of these are projects that people would like to take some initiative on.

Update: I’ve created a dropmark collection with documentation sections we can draw inspiration from. If anyone wants to add to it, set up a dropmark account and let me know your email address for it.