Dougal Campbell's geek ramblings

WordPress, web development, and world domination.

WordPress As a Documentation Platform

Twice now, the jQuery Podcast has mentioned that the jQuery project is going to migrate its online documentation from Mediawiki to WordPress. Which is pretty cool, because, I happen to like WordPress (duh). It’s also interesting, because when a lot of people build documentation websites, it’s pretty normal to choose a wiki. So, why would they want to switch an existing documentation resource from Mediawiki to WordPress?

One of the first factors is probably that the data in WordPress is more structured. In a wiki, you can add some structural information, but there’s not a lot of enforcement, and there’s only a few bits that help you with searching and such. Another factor is probably that it’s much easier to theme WordPress, so you can create custom page layouts depending on what type of content you are displaying. And lastly, I’d guess that ease of use plays a part. WordPress is very intuitive for many content management tasks.

This is also interesting in light of recent discussions started by Matt on the wp-hackers mailing list about the creation of a new Developer Portal. Many have stated that they think such a portal should itself be powered by WordPress. And with the recent addition of custom taxonomies and the upcoming improved support for custom post types, that certainly seems like a great project idea.

If there were to be a developer portal for WordPress, someplace where if
you’re first getting started with hacking on WP, building plugins,
creating themes, you could go and it’d have all the best resources in
one place, what resources do you think would be important to have there?

What do you wish you had when you first started developing for WordPress?

(Bonus points if it’s something that already exists, just scattered
around. :))

I’m not an Information Architect, so I’m not sure how I’d go about it. I would probably examine other documentation sites and try to discern what made some better than others. How do you think you would organize a WordPress Developer Portal?

About Dougal Campbell

Dougal is a web developer, and a "Developer Emeritus" for the WordPress platform. When he's not coding PHP, Perl, CSS, JavaScript, or whatnot, he spends time with his wife, three children, a dog, and a cat in their Atlanta area home.
This entry was posted in WordPress and tagged , , , , , , . Bookmark the permalink.

19 Responses to WordPress As a Documentation Platform

  1. Otto says:

    It is my opinion that correctly documenting open source projects which are rapidly evolving is not possible.

    Quite simply, documentation is a LOT of work. It’s work that needs to be done by people who are intimately familiar with the code. However, those people are also your most valuable ones, and you really want them to be creating new features and functionality as much as possible.

    So the only real solution is to have a documentation team, who do nothing for a while except create a stable set of documentation, and then are willing to continually update it as time goes on. However, this in itself is a pretty crappy solution, because documentation, on the whole, is of little value.

    Yes, I said it. Documentation is pretty worthless. Okay, yeah, it’s useful to have functional documents which explain the details of how to use function x(y,z), but those can be generated directly from the code if your commenting system is up to snuff (and WP’s is now, BTW). But something like a “big book of WordPress” is pretty useless. Only newbies need it. And while it’s important to make it easy for new users, presenting them with a big book of docs is rather intimidating.

    People don’t learn programming by reading books. They learn by getting in there and doing it. They make mistakes, they search for tutorials, they search for snippets of code to cut and paste. If they’re capable of learning at all, this rapidly builds into a decent working knowledge of the system in question. If they’re not capable of learning via this method, then giving them a big book isn’t going to help.

    Good documentation is a waste of time and energy.

    A ‘developer portal’ should consist of nothing but tutorials. You’ve seen these around on various sites. You’ve written a few. Heck, I’ve written a few. What you need is to teach one thing, and then let people learn that thing. And, it needs to be a relatively new thing most of the time.

    When I sat down to try to figure out the WordPress Settings API, I made myself a little document of functions I needed, where I’d put things, etc. These eventually became a short tutorial on how to make settings pages. It was exactly the same process I did to create the tutorial on how to make 2.7 compatible comments templates.

    What we need is good developers who sit down and learn some new thing to create tutorials for that new thing. Then to post those tutorials on some central site. Well tagged, well indexed, easily searchable. If somebody searches for a function name, then they don’t need the details about that function, or even minor little examples of using it. What they need is an article that puts that function in context with the rest of what they’re trying to do.

    That’s what should be in a developer’s portal.

    • Dougal says:

      I think that saying, “Good documentation is a waste of time and energy.” is a bit of hyperbole. But yes, it is definitely hard to keep documentation up-to-date when you are trying to document a moving target (like most Open Source projects).

      Of course, the usage and requirements for the jQuery documentation and the proposed WordPress Developer Portal are different, too. The jQuery guys might have it easier, if the main focus is to document functions and provide examples. A lot of that could be automated, generated from source docs. The Developer Portal is probably going to be more of a “prose” resource, with handwritten copy. So keeping it up-to-date will be more problematic. For each new release of WordPress, people will have to review each bit and say “is this information still valid? does it reflect current Best Practice?”

    • I totally agree with the documentation issue. The problem is that the evolution is so fast and expansive. I think of writing up all this information for wordpress (or druapl or joomla or magneto or gnutch or etc.) and I find it simply to be not helpful. Learning by trial and error is the only way to really learn.

      I do agree though with tutorials. I don’t want a mega-text discussing an open source platform. I want a solution to a problem. That is it.

    • Rich says:

      “Good documentation is a waste of time and energy.”

      That’s the problem in a nutshell. This attitude makes perfect sense from a programmers point of view but not from a users. The jury is out on the business case but I believe that it is leaning toward good documentation.

      As a new user to a product it can be impossible to make software function without instructions and especially tutorials.

      From a business point of view, creating and maintaining good documentation is a very expensive proposition. Without it how many customers will you loose or never acquire? It’s hard to verify the value of not having as may support calls or loss of productivity handling support but these are real numbers that must be considered. Large software companies all have documentation and for many programs there are classes and schools.

      I am of the opinion that if you are in the “Good documentation is a waste of time and energy.” camp than you are doing a disservice to your users and probably you profitability. Certainly you are choosing to be unprofessional. I understand the mentality behind it as who has the time or the money to do it but I think if you want to have the reputation needed to grow you must provide the support services appropriate for your customers and the first step is proper documentation.

  2. Pingback: uberVU - social comments

  3. chrispian says:

    I’ve been toying around with the idea of using WordPress for various documentation projects, among other ideas. So to say I love the idea is a bit of an understatement. Adding a couple of plugins, like a syntax highligher, I’ve created a local wordpress install that I have all my code snippets, hacks and other code bits organized with. I think it would work great for just about anything you’d want to document, collect or organize.

    • Ben says:

      @chrispian: Are you still using that local installation for your snippets and code? If so, would you be willing to discuss how that has worked out for you? I’m looking at implementing something similar, and would be very interested in what conclusions you’ve reached over the last two years.

      Thanks!

      (In hopes you will get a notification of this, I’ll ask here, but will attempt to follow-up through other means)

  4. Matt says:

    Curious to see how they approach it. I’d love to ditch Mediawiki as well.

    • caesarsgrunt says:

      Yeah…

      Isn’t it a bit embarrassing that the company which basically owns WordPress is still using MediaWiki when others are already switching to… WordPress!

      Seriously, though, I’m interested too to see how they go about it.

  5. Matthew says:

    I was building a wiki a few years ago for my work and we looked at a variety of solutions. We’d piloted Mediawiki but it just wasn’t good enough. Too free-form for our needs, not enough security or control, no good way to organize, hard to tie in with LDAP for authentication…

    I considered WordPress briefly, and I hope to transition our site to it soon (we’ve actually got it built and about 90% done, I just haven’t had time to go back and polish it yet), but it didn’t seem like it’d be quite big enough for what we needed. Too much work to make it what we needed. We went with Atlassian’s Confluence instead, which has been pretty dang good.

  6. After 16 years of using U&ix, I still read man pages. The difference is that now I understand them. Back in the olden days, I had wished the man pages had more examples.

    Striking the right balance between reference and tutorial is rather difficult; I think there’s a place for both.

    (BTW, who owns “Unix” this week?)

  7. caesarsgrunt says:

    A “DocPress” plugin would be nice, kindof like what it sounds like bbPress is going to become for forums, but for documentation. Or even a generic WikiPress (oops; better be something other than WikiPress…)

  8. Martin says:

    Hello. I am personally not a fan of wordpress. when I see such blogs like this one really just the advertising makes …

  9. Pingback: Dougal Campbell’s Blog: WordPress As a Documentation Platform | Webs Developer

  10. It would be interesting to see how WordPress can be used for documentation. I believe wikis are better suited for documentation, but the jQuery project would through up interesting ideas

  11. Pingback: jQuery API site using WordPress as CMS

  12. Alistair says:

    I still think one of the best documentation efforts is Django. It is well structured, easy to read and provides a good balance of beginner through to expert levels of documentation.

  13. Ivan Koval says:

    It would be interesting to see how WordPress can be used for documentation. I believe wikis are better suited for documentation, but the jQuery project would through up interesting ideas

  14. WordPress is great for just about anything. It is a great mix of power and flexibility. And it is super easy to use and free… doesn’t get much better.

Leave a Reply

%d bloggers like this: