Cancel

Jeff Chandler

Do You Think The Codex Is The Future Of Documentation For WordPress?

During the past few days, I’ve been participating in an interesting discussion revolving around the state of documentation for WordPress, namely the Codex. The discussion centered around the fact that although the Wiki approach was good in the beginning, it simply doesn’t make sense today. Quality has gone way down, there is a ton of trash in the way of the good stuff, and in some ways, it’s difficult. At the end of the day, all involved in this conversation agreed that the Codex would not be the future for WordPress documentation. I leave it up to you now to place your vote and your opinion in the comments.

[poll id=”24″]
Category:
Tags: , , ,
18

18 responses to “Do You Think The Codex Is The Future Of Documentation For WordPress?”

  1. I still use the Codex as one of my main resources. It is definitely difficult to get started using the Codex, but once you’re used to the structure (and once you realize Google provides a better search than the built in search) it can be a valuable resource. Rather than doing away with the Codex, I would like to see better management and more control of users. I might even like to see Automattic hire a “gardener” to prune and water it full time. There is a wealth of WordPress information in the community. If we could only organize it better, the Codex would be an amazing resource.

    Create forum topic from comment

  2. @Will Anderson – What if you took the best that the Codex hand to offer, segmented it into various projects/categories like Themes/Plugins/Core Development/End Users etc. Each handbook is managed by Trac which still allows for end user contributions but allows for quality control. Instead of cleaning everything up. Leave the Codex there but build something new and start over.

    Create forum topic from comment

  3. The codex is utter crap when it comes to finding info. Especially in regards to the hooks and how to use them.
    The layout, the examples, just about everything except the function list I find of very poor quality. (And most is for use with PHP4. examples should include PHP5 because its much better.)
    Just take the add pages to the admin for example. There lack a couple of functions there. For example add_object_page which adds an page that doesnt show in the menu. Very useful but nowhere to be found in codex.

    Oh well. I really don’t like the codex in any way shape or form. well its better than nothing =)

    @Jeffro – Aint that what Jane? talked about? Making different versions requires different type of language also. First separate end user and developer . Then you can devide each to sub categories. I can think of a bunch of stuff but I would probably have to write a blogpost about to get it all down.

    Create forum topic from comment

  4. I would like to see something more than a wiki as the codex base. I use a few pages all the time, such as Template Tags, and Functions Reference, but for the most part if the information is not available on one of those pages, then the quality starts to drop off dramatically. Even the simplest of structure is ignored in places … heh, I’m not a fan of wikis so I will stop before I get to a real rant.

    If they could combine the “ideals” of the current codex with the details of trac I think they would have a real “Go To” documentation reference.

    Create forum topic from comment

  6. @Viper007Bond – wikis are both a blessing and a curse. It all comes to how its managed and supervised and who is writing the texts. If there is an elite that decides what is good and what is bad it will end up as bad. Also if everyone is allowed in.
    Wikis for this stuff are totally useless if they aren’t organized properly. I only see continued failure in the future with the wiki path.

    Create forum topic from comment

  10. I’m not sure if the Codex is in it for the long haul or not, and I think that’s half the problem with it. I often see things that I want to fix or add to, but I’m hesitant to contribute if it is going to be retired in favor of handbooks or some other alternative.

    From what Jane was saying in the latest episode, i got the impression that the Codex was going to stick around and that the handbooks would be in addition to the Codex. Which would be fine in theory, they could serve different purposes.

    But it seems like as a whole, the Codex is already the most neglected part of WordPress, splitting attention between that and multiple handbooks could cause it to suffer even more.

    I don’t think the current wiki is that bad, lots of good info, just needs strong editorial oversight to clean and organize it. I’m ok with a wiki, handbooks, or just about anything though. As long as it is well maintained I’ll feel more confident contributing to it.

    Create forum topic from comment

  11. They should make documentation marathons on the most important topics, where volunteers got some access to devs/experts to request some insight in missing info. Its all about organizing the content production. Once the content is produced it may be published in many ways.

    Create forum topic from comment

  12. @JLeuze – I agree with the strong editorial hand on the codex. Not that I have made any major contributions, but I got so tired of scrolling up and down in the Function Reference that I stopped what I was doing and Alphabetized each category on that page.

    I would contribute more where I could if I believed it was going to be the “go to” reference, but I would also agree it does not lend itself well to confidence building in its current state.

    Create forum topic from comment

  13. @Edward Caissie – @John Myrstad – That’s a good point, quality content could be used in many ways, so I guess the handbooks could contribute to the improvement of the Codex in that sense.

    @Edward Caissie – Yeah, confidence is hugely important. That’s why I have devoted so much time to learning WordPress, I trust that the developers and the community will continue to thrive and make improvements. Who wants to spend time learning a dead language so to speak?

    Create forum topic from comment

  14. @Andreas Nurbo – I can’t remember what was said regarding different languages but I can see the different handbooks having separate downloadable translations much like WordPress so it’s not all bundled in one place which is one of the problems the Codex has.

    @Edward Caissie – I’m pretty sure that’s what this new documentation project is going to do. Take the best of both worlds and combine them into one. I imagine it will be much easier to manage as well.

    @Viper007Bond – Hmm, even after the work that could be put into the Codex, I think it would be curing a symptom of a larger problem. With a streamlined managed way of handling the documentation instead of it being a free for all I believe is the way to go. Thankfully, it seems to new documentation project still have that free for all feel.

    @Martin – I’m the same way. Would be nice if I put in a function or template tag exactly how it is, that it would be the first search result. But usually, it’s a page buried somewhere within the results that I have to go search out.

    @Lyndi – Well, the Codex isn’t going anywhere anytime soon so the new handbooks will be IN ADDITION to.

    @JLeuze – You hit it on the nose. I think attention will be steered more towards these handbooks at least for a few months to see how it goes. I imagine if it doesn’t go as planned, the Codex will be there as the backup plan and perhaps, might go through a revitalization effort.

    @John Myrstad – I don’t understand how that would help as wouldn’t be better to just have the Core developers/experts write the content in the first place? They are too busy for that so I don’t see how this could be feasible.

    Create forum topic from comment

  15. @Jeffro – I meant language as in the level of detail, wording etc. Function documentation does not sound the same as a “tutorial” on how to make a post. Level of detail etc. Also then there is the problem of different levels of experience. Where do you set the bar in terms of complexity and things not said.

    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.