codex is dead. here are some suggestions on how to resurrect it.

This is one of those posts that started off as a comment and grew out of control, so for context, go here and come back when you’re done.

I did a bit of codex-related ranting on livejournal, I should probably import those posts🙂 The fundamental problem is that documentation is far less suited to a collaborative open-source approach than code. To write decent documentation (which is more like a book than a piece of software) you need an editor/manager with a clear roadmap of what you’re trying to do and how it’s going to be accomplished; but as soon as someone steps up to the plate and starts laying down the law everyone else starts grumbling about how authoritarian they’re being, disagreeing with their ideas, and generally focusing more on internal politics than getting the job done. Result? Bruised egos and chaotic docs.

If Matt genuinely cared about documentation, he’d have appointed a decent technical writer at the outset to oversee the project and get things organised. People are much more willing to accept the authority of official leaders than self-appointed ones. In the early days of the Codex I got tired of my contributions being mangled by fellow contributors who couldn’t even spell right and were obviously just desperate to get their fingerprints on every page they could (you could say that’s the nature of wikis, but that’s why wikis need managing by people who know what they’re doing). Later on, it became pretty clear that newcomers weren’t welcome and the whole thing had degenerated into an egofest. Meanwhile, if I want up-to-date information on a template function my best bet remains to go directly to the code, just as I had to in the days of 0.72. There’s no way codex can keep pace with development when there’s zero communication between developers and documentors and the devs have abandoned it in order to focus on sexier, more lucrative projects.

Best thing to do? Freeze contributions from the general public. Hire someone to sift through what we have. Keep the useful stuff (by this I mean actual documentation that people can access from their admin pages, not half-baked tutorials which would be better off on a subdomain of wordpress.net). Go through the useful stuff and ensure it’s still useful. Rewrite. Restructure. Tag stuff. (I put that suggestion in there in the hope of getting Matt interested, rather than any great belief in its codex-saving powers. But it may be useful, and should be done). Re-open the wiki with a call for volunteers and a set of rules for them to abide by. Focus on documenting everything in 2.5. Then the wordpresstutorials.com groupies we met in the last post and its surrounding wank will have less compelling arguments for the necessity of their illustrious sponsor, and wordpress will look a fair bit more professional.

It will not be quick, and it will not be easy, and the temptation must be to junk it like the original wiki and start again on yet another subdomain. If any part of wordpress needed a benevolent dictator, it was the docs. It’s a shame it never had one.

7 Comments »

  1. Andrea_R said

    Here, here. Don’t even ge tme started on the documentation (and lack thereof) for MU.

  2. I think the general attitude towards MU is ‘if you’re n0ob enough to need docs rather than figuring it all out yourself by looking at the code, you shouldn’t be using it.’ WordPress itself was pretty much the same when it first took over from b2. It drove me nuts, because I knew it was easier to install and use than Movable Type, yet they seemed determined to make it seem as difficult and obscure as possible. I’ve been crusading ever since🙂

  3. Derek said

    You absolutely hit it on the head. My POV is one of someone who is not a coder by any stretch, but want to be able to take advantage of the cool things WP has to offer in the way of customizability (if that’s a word…). Let me be clear that I have great respect for the knowledge, time and effort that the WP team puts in to make it what it is, and I have no inclination to switch to another blogging system at this time.

    HOWEVER, both the codex and the forums are damned hard to use. Finding answers in either the forums or the codex is a “needle in a haystack” endeavor, said haystack largely composed of info that is a year or more old. I end up frustrated that the amount of time I’ve spent hunting for an answer is time that I didn’t spend blogging.

  4. If any part of wordpress needed a benevolent dictator, it was the docs.

    Agreed. It’d likely be a full time job, too.

    I love helping people and answering questions, but I detest writing documentation and I don’t think I’m very good at it. But if there were an official Codex maintainer, I’d be happy to keep a line of communication open for clarification, assistance, and notification of changes to core WP functionality. Much in the way that Lloyd is helping sort, filter, and manage the bug system, we could use such an intermediary for documentation.

    A good start would be going through and wiping out any old WP 1.5 or 1.2 stuff. That’s only going to confuse people. Also, a lot of the Codex seems to be suffering from “TMI” syndrome. Less is more. Focus on the best way to accomplish something… not every possible way there is to do it. And come to the people who know for clarification. I’ve seen some really awful advice on the Codex… stuff that could be done right if only someone in the know were consulted.

  5. […] As always, NTU has raised some good points but this time, it has given me a reason to get started on something big and challenging – namely, rewriting the WordPress Codex for myself. […]

  6. markku said

    I used to get lots of emails asking for help on WordPress. I usually go to the codex and explain it more simply to my readers to solve their problems. Nowadays though, even I have a hard time finding what I need. Heck, I couldn’t even find the pages I used to read a lot for reference.

    There should be an darth vader of sorts to impose will on the whole codex.😉

  7. Christine said

    I remember when I started using WP (back in the pre-1.0 days) and I would ask for help on how to do things. Often, the answer was “Just go to the codex!” Yeah, right. Even then you could not find what you needed.

    Documentation has always been the biggest thing lacking with WP, in my opinion. I remember the early releases of MT, and they always had nice documentation included with the release. WP? Well, hopefully you can just figure it all out. Or find someone to help you. Because the Codex does not cut it.

    It needs an overhaul, and they need to hire someone to do it. You are spot on with that!

RSS feed for comments on this post · TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s