rip codex. oh, sorry, i meant R.I.P. codex.

So, according to Lorelle, Codex is officially dead and being superceded by the WordPress HandBook. Lorelle being Lorelle, she doesn’t admit that Codex is officially dead, but nor does she provide any coherent explanation of how and why two ‘online manuals’ sharing much of the same content can operate side by side. (She can’t seriously believe that Codex will still have a role as ‘a highly technical and historical guide to WordPress’. Firstly, the techies wouldn’t touch Codex with a bargepole, they’re all about the PHPXref. Secondly, a historical online manual is about as much use as a chocolate teapot, otherwise we’d still be directing people to wiki.wordpress.org so they could read about how to get the best out of 1.2.)

Obviously, switching from mediawiki to XML and SVN is going to effectively debar all but the most dedicated from contributing (for which, read Lorelle and people on the Automattic payroll), but that’s not a bad thing, since a) Codex was not exactly overwhelmed with volunteers, the docs project being a proud part of the long-standing WP tradition of treating volunteers like crap, and b) community-written documentation is next to impossible to keep up-to-date, especially when pursuing a quarterly release schedule. Bringing it under the Automattic umbrella at least means that it will be updated, even if it does constitute another step in the process of taking the community out of wordpress and wordpress away from the community.

It’s nice that Automattic have decided to focus on documentation this cycle — it was about time — but I can’t help wondering how much cross-referencing will be going on between the new written documentation and the new proprietary traffic-building ad-carrying video stuff…

14 Comments »

  1. Matt A. said

    I don’t know. The new handbook doesn’t sound like it’s going to be sufficiently technical to satisfy the needs of this user. I can’t imagine going to that kind of handbook to figure out anything after the first couple days using wordpress.

    Incidentally, I saw a handbook like this in Barnes & Noble last month. I stood in the bookstore and laughed as I read through it; they were charging $15 for the most basic of basic instructions that are available for free online.

  2. whatev said

    I don’t think the initial Handbook will supplant the Codex, it’ll be the eventual “developer” edition that will do that. In and of itself, having a more structured and centralized repository of “official” documentation isn’t a bad thing; it makes sense for a project of WordPress’s size. The problem is, because resources have been so scattershot for so many years, the “community” has created various solutions to varying degrees of success and I can’t see some long time contribs reacting positively to being pushed out. Had WP had proper official documentation like Django (if they want to copy a model for documentation that addresses regular users and devs, djangobook.com is a far better example than Subversion’s manual…esp. since all the cool kids use Git now anyway), they wouldn’t have the types of conflicts that are sure to happen in the future…

    One thing is for certain, the “the documentation sucks because it is all volunteers” excuse won’t fly anymore. They better be prepared to keep shit accurate and updated.

  3. they were charging $15 for the most basic of basic instructions that are available for free online.

    It’s like the difference between paid software and open source software that’s available for free. Folks think they have to pay for something to get any value out of it.

  4. Kissing Bandit said

    Or some people appreciate having a hard bound reference manual next to their computer rather than needing to flip back and forth between an free online reference site*.

    You and I may never need to purchase the $15 Dummy’s book because the stuff is all available free at the Codex and we’re willing to do the switch between because, I assume, we have some basic technical knowledge to begin with and aren’t necessarily afraid of breaking something. But the everyman doesn’t exactly see it that way.

    And that brings me to the reason why I believe the WordPress Handbook won’t pan out. The information it will encompass will likely be too basic for anyone who’s been using WordPress for any length of time and for the everyman just starting out, who also has limited technical abilities, the actual writing style will be too complex. Unless they have a truly dedicated team of writers who understand how to write instructions for the layman, it will be a bust. (Just look at the comments on the Codex content, then read the comments left by those people kind enough to write plain English tutorials on their blogs….)

    * Many people don’t like to run prints from their printers unless it’s of an already written/edited book written for the layman and that makes people less inclined to run off copies of the Codex pages since 1) they aren’t written for the layman and often people become confused reading it; 2) many of the Codex pages are incomplete or having errors which are slow to be fixed; and 3) the Codex, in general, is a maze to navigate–who wants to comb through 100 of Lorelle’s blog posts explaining how to use to Codex just to figure out how to write a post on their blog for the first time? It defeats the purpose.

    Climbing off my soapbox now and I apologize if this comment seems in any way incoherent, I’m running on little sleep.

  5. Matt A. said

    Kissing Bandit is probably right, of course. When I say basic, I mean that there were several pages on how to upload an image onto your blog with step-by-step instructions that included step-by-step screen captures of said instructions.

    It’s the kind of things that people (I would suggest older people) might need for about the first day. It’s like having a guidebook on how to start your car with pictures of a hand inserting the key, then the hand turning the key clockwise. Coming from a nation of capitalists, I’m sure at one point such a thing was published as well.

  6. Kissing Bandit said

    Well, I just learned yesterday that MB (Mercedes Benz) actually employs a single person who’s only job is to show people how to use their car, including how to open the car door. So, apparently, some people do need that kind of hand holding. (Nothing wrong with that. It’s completely new territory to some people and, as such, people tend to me a more over cautious for fear of making a mistake and irreparably damaging something.)

  7. heh🙂

  8. I noted that Lorelle is denying that the codex is going to go away on the mail lists. From the experiences with the theme and plugin depositories as well as the updated FAQ blog over at wp.com, I give it six months.

  9. And of course Lorelle deletes the comment that I left as well as your trackback from this post. It’s interesting that she leaves the multiple splog trackbacks though.

    Considering her behavior lately, it doesn’t surprise me.

  10. Well, the codex doesn’t have to go anywhere in the immediate future. Matt can leave it on the wordpress.org servers till it festers into irrelevance, like he did with themes.wordpress.net, and then silently get rid. There is simply no way that a multimillion dollar corporation can continue to delegate documentation to amateurs. It just doesn’t look good.

    Newbies, as I see it, will be well-served by the wordpress.com FAQ, the new HandBook, and the wordpress.tv tutorials. Developers will continue to work stuff out for themselves or ask each other. When I was developing themes a few years back, I found there was more useful information in blogs than in Codex. If somebody writes a half-decent tutorial they’re going to keep it on their own site for the traffic and backlinks, rather than hand it over to Codex and deprive themselves of all rights over its editing, copying and redistribution. (GPL is a lousy licence for creative works, but it is a truly lousy one for documentation.)

  11. Barry said

    amen to @that girl again. The only use I’ve made of the codex in the past 2 years is when I fail miserably to remember the functions that add menu items form within plugins – don’t know why, but I can never remember the order of the variables.

    For everything else I Google and read tutorials on blogs, and my tutorials go straight on my blog.

    Not really had much time for Lorelle, though why are these announcements are made on her blog and not on a “WordPress” blog?

  12. andybolton said

    Google the overlord … I didn’t realise the saying originated from @that girl again…
    🙂

  13. Ching said

    Just dropping by.Btw, you website have great content!

    ______________________________
    Why this one-minute therapy is being suppressed in the U.S. while more than 15,000 European doctors have been using it to heal millions of patients

  14. ray said

    Yay – more spam!!

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