Cancel

Jeff Chandler

Interview With Siobhan McKeown On The Future Of The WordPress Codex

If you use WordPress, chances are that you’ve run into the WordPress Codex. The Codex is a community maintained collection of documentation, hooks, filters, best practices, and other information related to WordPress. With various handbook projects underway, I’ve been wondering what the future of the Codex is. To find out, I got in touch with Siobhan McKeown, who is a member of the documentation team.

Interview With Siobhan McKeown

Is the roadmap outlined here still accurate and is it being followed? Is it still on time?

The roadmap is still fairly accurate but it’s not on time. The number of contributors to docs is quite small and we’ve faced challenges around getting development work done and finding people to write. That said, the people who are involved are very dedicated and we’re slowly chipping away at things. We have made big strides forward, particularly in the area of inline docs (thanks Drew Jaynes and Kim Parsell) and in building developer.wordpress.org.

Ultimately, is the future of the Codex for it to disappear in favor of all the other documentation resources outlined in the roadmap?

I would like for that to happen, but the decision doesn’t ultimately lie with me and it’s a discussion that we’ll have to return to once new documentation is in place.

Many free software projects in the early stages of their life use a wiki for their documentation. Over time, this can become out-of-date and inaccurate. As a project grows, it often out-grows a wiki, requiring more targeted documentation for both users and developers. Firefox and Ruby on Rails are good examples of FOSS projects that provide the types of targeted documentation that WordPress should be providing. I would hope that we can eventually get there ourselves, and keep the Codex as a historical archive.

Mozilla FireFox Targeted Documentation
Mozilla FireFox Targeted Documentation

Is it a waste of effort and energy for folks to continue to edit and update the Codex?

No. For two reasons: First of all, while all of the docs work is going on, we need to ensure that the Codex stays up-to-date and accurate. It remains WordPress’ primary source of documentation and will be for some time, so contributions are still valuable there. When a new version of WordPress is released, the docs team usually does a sprint to get the Codex up-to-date.

Secondly, the main problem with the Codex is its navigation and structure. There’s a lot of good content in there mixed with a lot of out-of-date content. As we create new resources, we look at the content in the Codex and migrate good-quality content. If you fix a page in the Codex, then it’s likely that will end up somewhere in a new documentation resource.

How can folks get involved with helping the roadmap move along?

We particularly need help in two areas:

  1. Someone to help with ongoing development of WP-Parser (the parser used to generate the Code Reference). A lot of things are on hold until we get someone helping there.
  2. Writing the theme and plugin developer handbooks. These have been around for a long time and we really want to get them finished off so that we can move on to focusing on user support.

To Some, Google Is The WordPress Codex

It may be the largest collection of WordPress documentation but I bet it doesn’t compare to the amount of WordPress content published on sites across the web. The paradox of publishing content on the Codex for the benefit of everyone versus a personal site for the benefit of a small audience has existed since it was created.

I think it would be awesome if content from sites like Justin Tadlock found a home on the Codex but perhaps we don’t need one at all. Maybe all we need is Google. When I asked the Tavern’s Twitter followers what aspect of WordPress do they take for granted, Jared Novack submitted the following answer:

https://twitter.com/jaredNova/statuses/494322903739936768

If the Codex ever goes offline, it will be a sad day. However, if it’s replaced with easy to navigate, skill level targeted documentation, with a solid code reference, I think a lot of users and developers will be happy with its replacement. Has the Codex saved your bacon once or twice? Let us know in the comments.

Category:
Tags: ,
9

9 responses to “Interview With Siobhan McKeown On The Future Of The WordPress Codex”

  1. I’d miss the Codex were it to go. I’m not a novice, nor am I an expert (after several years :-) ) but I’m also not afraid to look things up and have a go. The Codex at the moment points me in the right direction and lets me try and work the rest out for myself; and if I can’t then I can always Ask Jeeves for some guidance.

    Create forum topic from comment

  2. I hope changing codex to more formal version, doesn’t end up like documentaction for other CMSes such as joomla and drupal. If users have to navigate between different versions of documentation, it would be a nightmare. It may be easier to maintain documentation for each version from admin point of view, but I like something which make sense when we don’t have to juggle around to find what we want.

    Create forum topic from comment

  3. The MediaCommons Wiki platform’s greatest weakness has always been the lack of quality navigation design. We’ve battled with that since day one. I’ve always been a fan of coming up with a better system to organize it, but I’m not a fan of throwing out the baby with the bathwater.

    As discussed early in the project to create the handbooks, the key purpose of the Codex is to host information that needs to exist outside of the handbooks. There are excellent articles and information about WordPress features, tips, and techniques that have no place in the handbooks, but the Codex serves as a brilliant repository to help so many.

    Create forum topic from comment

  4. Like nearly all software projects I’ve encountered, the WordPress one suffers from documentation debt. It’s a situation that, in my opinion/experience, is likely to get worse before it gets better, unless something fundamental changes about the working practices.

    Why? Well, because most architects, designers, and developers are busy and enthusiastic; getting on with their tasks. Documentation isn’t usually part of their arena. Perhaps it should be. Imagine how much easier things would be if the documentation were done more in parallel with the development of other collateral, such as the source code. I think this can only happen if the developers become stakeholders in the documentation components.

    It’s probably a lot to ask, and possibly too much of a large or unwanted change to established procedures, but otherwise I think you’ll forever be playing catch-up.

    Create forum topic from comment

    • I agree that shifting the onus to core team is an important step toward decreasing documentation debt as you put it. In the 11 months I’ve been the docs committer for WordPress core, this has been one of the primary goals.

      That said, moving to a parsed code reference, in my opinion, is a giant step toward strengthening the parity between what’s been changed and what’s been documented — when it comes to functional docs. If there’s an expectation that missing documentation is a bug and not something we can just “catch up on later”, that mentality-shift alone will be worth the years of effort put in up to this point.

      Create forum topic from comment

You may also like

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.