9 Comments

  1. Gary Taylor

    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.

    Reply

  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.

    Reply

  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.

    Reply

  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.

    Reply

    1. 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.

      Reply

  5. Hi Jeff,

    I actually gave a talk about this (and the handbooks) at WCNYC last weekend. It should be up on WordPress.tv soon.

    Reply

    1. I’m eager to see your presentation, but confused by the web page you linked to. It’s the WordCamp NYC, but the post doesn’t say who did the presentation or have any notes or slides.

      Will those, plus the WP.TV video be added to that post? I’d love to know more on that subject.

      Thanks!

      Reply

  6. The Codex has helped me tremendously over the years! It’s not perfect, but it is a valuable resource.

    Reply

Leave a Reply