WordPress Documentation: Goodbye Codex, Hello HelpHub

WordPress Documentation: Goodbye Codex, Hello HelpHub

One reason WordPress is such a popular CMS is that it’s so easy to get started with a site. Pick a name and a login password and you’re in. While the first bump in the road is choosing a theme, the Customizer goes a long way toward solving some of those initial issues of “what should my site look like?”

The other freak out moment in a new user’s WordPress journey is usually when something unexpected happens. You’ve probably had this moment; you’re thinking (or screaming) “I can’t do X!” or “What does this message mean?!”

Of course, there’s always the wish-list moment: “How can I make some text, image or other feature appear on my site?”

Unlike software you install and run on your computer, WordPress doesn’t have a help system that appears when you press F1, but it certainly has a place to get answers to those pesky questions. Chances are you’ve been referred to the WordPress Codex when you run into a problem. Maybe you’ve been intimidated by the technical language when you get there, or you think the Codex is for coders (it’s not).

If any of the things you’ve just read resonate with your experience finding help with a WordPress problem, know that the WordPress documentation team has heard you. It will get better, but you’ll need a little bit more patience.

The future of WordPress docs is called “HelpHub” and it will be ready in 2018.

What’s Wrong with the WordPress Codex?

For WordPress newbies, the WordPress Codex is an important resource and the articles are generally useful. It can be hard to find the right article you’re looking for, though. The Codex front page tries to point you in the right direction, with a variety of links.

Right near the top is “Learn How to Use WordPress.” Sounds like the right place. Then you see links to two articles that sound like they cover the same ground.

First in the list is Getting Started with WordPress, which is just another batch of links. Excellent in navigating the landscape, but you might get confused seeing some articles listed under both the Beginners and Intermediates sections.

WordPress Codex
The Codex can be confusing for the WordPress beginner.

One of those articles for Beginners and Intermediates is also linked to on the front page, right after Getting Started. It’s called New to WordPress – Where to Start. This article offers a well-written “step-by-step plan for getting started.” It advises you on planning your site, installing WordPress, picking a theme and choosing plugins. This article is filled with links to more in-depth treatments, but with descriptions of those articles as well.

Similarly, dealing with a problem can be troublesome too. The front page section, What You Most Need to Know About WordPress, points you to the Troubleshooting category. Listed here are links to Frequently Asked Questions, and articles on Installation issues, design and layout, and dealing with comment spam.

Too often, when you get an error message, or some perplexing issue that doesn’t quite fit into one of the prepared categories leads you to the Forums. There you might get a pointer to the right article dealing with your problem, or something relevant that someone else used to solve a similar problem.

Tip: The Troubleshooting page, under Finding Answers, offers a nice summary of How to Write a Great Support Request. Do read that before you hit the forum!

What’s HelpHub?

Let’s look at HelpHub’s goals, as outlined in the project specification.

For users, the goals are simple:

  • Replace support content (mostly on the Codex) with high quality, easy-to-understand articles.
  • Create a searchable repository that makes it easy for users to find content.

HelpHub also offers benefits for the WordPress support team:

  • Reduce the amount of support forum posts by making it easier to find answers in HelpHub.
  • Provide a reference that support forum volunteers can link to for common questions

Models: Mozilla and DevHub

The models are much like other complex sites and apps with household names; Apple, Google, Mozilla (Firefox). When you arrive at the site, you can ask a question and find answers to that question, or a solution to a problem you’re having.

To get an idea of what HelpHub will be like, see support.mozilla.org, the support site for the Firefox browser, Thunderbird email client, and a variety of other products and projects.

Today, if you visit support.mozilla.org, you see a list of Mozilla products. Click on Firefox, and you get a set of areas like Install and Update, Manage Preferences and Addons, and Protect Your Privacy. Click one of those buttons, and you get a series of articles related to that button.

More to the point, look at the new WordPress DevHub. The Documentation team calls this DevHub. The site offers links to the existing developer handbooks for theme makers, plugin developers, folks who want to know more about the REST programming interface and the new Command Line Interface (WP-CLI).

Documentation team leader Jon Ang describes the difference between DevHub and HelpHub like this: “If anyone thinks, how do I use WordPress, they should think HelpHub. If someone thinks, how do I make something with WordPress, they should think DevHub.

Each of the handbooks is searchable, but a global search isn’t possible yet.

Speaking of search, Mozilla, Google and many other Help sites offer a global Search Support box. WordPress HelpHub will offer that as well. The team is looking for a faster, more effective search engine than the current WordPress search engine.

Better Quality Help from Support

HelpHub is a next-generation tool to help the Support team give users more, well, support. In the world of technical communication, it’s often said that the effectiveness of documentation can be judged by the number of “support calls prevented.” While with one big exception, you can’t call WordPress Support for help (that exception being the WordPress.com VIP program for big corporations), you can still improve the online community support.

Between the Codex, the Support forum, and email support (the latter staffed by both volunteers and Automattic Happiness Engineers), many problems are solved. But the Codex has been around so long, and development of WordPress core happens so quickly, some articles can be outdated.

To its credit, the Codex also has some of those “high-quality, easy-to-understand articles” that the HelpHub spec encourages. Take, for example, the First Steps with WordPress page. HelpHub will have many more of these.

When Will HelpHub Go Live?

In a June 2017 interview with WPTavern at WordCamp Europe, Doc Team leader Jon Ang said he hoped that an initial iteration of the site would be ready by the end of 2017, with the project complete sometime next year.

The Doc team is actively squashing bugs in the code, with a weekly “bug scrub” event. The Docs group is importing content from the existing Codex pages, getting it formatted, and editing it for better readability.

When it’s ready to go, it will be the place to get information and help with WordPress. You may be able to search a specific area of HelpHub globally, if you’re not sure what WordPress component is affected.

It doesn’t look like much now, but you can view a staging site of HelpHub today.

As the doc team builds HelpHub, you can take a sneak peek at https://wp-helphub.com.

Call for Volunteers!

You can help: If there’s something you’ve learned that you want to share with other WordPress users, the team wants to see it. As part of the HelpHub creation project, the team is working on creating guides for contributing with content and code. You can also help the team understand what information you need through user experience testing.

Want to keep up with HelpHub development? Subscribe to the Doc Team blog!

Michael McCallister
Got any Codex horror stories to share? What advice would you give to the Doc Team as they build HelpHub? If you're a developer, is DevHub more useful to you? Let us know in the comments below.