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.
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:
- 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.
- 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:
@wptavern You can type anything into google followed by "WordPress" and someone has already asked (and answered) it
— Jared Novack (@jaredNova) July 30, 2014
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.
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.