There has been some discussion on the wp-hackers and wp-docs about what a potential Upgrade documentation for WordPress 1.6 should look like.
I’m not a proponent of “simple is better” in documentation. At least, in terms of the WordPress upgrade, there is very little to do on the WordPress end to upgrade your system to the new version. Essentially, you push a button. But there are some steps you need to take before you get to that point to make sure everything runs smoothly, and that’s where adequate documentation comes into play.
I was thinking about what “Web 2.0” documentation looks like. We’re trying to play off WordPress as a state-of-the-art content management system. So why not have state-of-the-art documentation? The Codex is a good resource for WordPress, but there are users of WordPress that never need to know how to customize their software. These users will only want to know how to upgrade their installations, and the documentation should hold their hand through the process. So I assembled this silly mockup of what I imagined Web 2.0 documenation looked like.
Important bits to point out:
This is a step-by-step process that walks you thorugh the upgrade and that’s all. There is no other navigation on the page to confuse you as to what’s going on. When you complete a step (or select a path through the steps) you simply move on to the next page/step.
The first page of this documentation is linked-to from the download page on WordPress.org. So when you download the new version, you have a direct link to the installation documentation. Even better, there should also be a link on the installation page. If you already have the files on the server, then it may already be too late to perform a few of the steps, but at least you can follow along.
There are the links to the support forum and the Codex at the bottom of every step, so if you’re really lost or this information is too basic, you have somewhere to go.
There are illustrations of every step on the right side of the display. Even if they are just for show or a logo, I think it looks nice. In the case of this mockup, there could actually be pictures of different versions of WordPress. Clicking on one might do the same thing as clicking on one of the links.
Something that’s missing form this is a link that says, “How do I find my version?” The installation steps should all think of questions that a user might ask while they are on that step. But the answers should all lead back to the main path, eventually ending in an upgraded blog.
The very end of the path should provide links to “next steps”. Inform them that they’re about to be dumped into a larger resource (Codex) and provide links with suggestions based on what most users like to do after they’ve finished installing. For example, there might be a link to a Codex page that helps them find and install a new theme. There might be a link to another page that tells them what is new or different in the installed version, and where to find and how to use those features.
This is just a suggestion of mine, and doesn’t constitute the actual documentation. I figured I put enough time in the artistic aspect of it that I might as well write a bit about it and put it in front of people to get some response. Any thoughts?
