With all that’s been going on with WordPress development lately [see the nightly builds, or the CVS for alpha versions of version 1.2], one might reasonably wonder, what’s going on with the damn docs? Well, I’m here today to address just that question.
THE ISSUES
Nobody likes excuses, however justified. Nor do I like giving them, however justified. We’re all reasonable people here, and I’m sure it isn’t necessary to peevishly point out the fact ad infinitum that we all have lives away from WordPress and blah blah blah. We all know that. The hard fact remains that little has been accomplished with the ‘official’ docs (as opposed to the wiki, which has been steadily updated since its inception) since the release of version 1.0 in early January.
Part of the problem is the rapidly changing face of WordPress itself. The CVS is currently at version 1.2-alpha, with almost daily updates. 1.2, which will be the next official release, is much different from the widely used 1.0.1/1.02 series, and even more different from the still-used .72. There’s new functionality, new template tags, new database tables. This will be a great release, with many of the new features incorporating requests frequently found in the forums (such as subcategories and advanced editing controls).
Up-to-date documentation has always been the weak point of open source (and other) software development. In short, many times the documentation effort simply cannot keep pace with developments in the software. Everybody wants documentation, everybody needs it, but nobody wants to write it. (Including myself, at times.)
WHAT WE HAVE
So what do we have? We’ve got a pretty barebones readme for version 1.0.1. We have the wiki, which now has a useable index thanks to Craig Hartel. And of course we have the forums, which are a treasure trove of useful information in their own right.
Offsite, we have a few resources on miscellaneous topics: Podz has created helpful guides on FTP and CHMOD, as well as a graphical guide to wp-layout.css. NuclearMoose also has an annotated guide to the default style sheet. I’ve written a howto for downloading the CVS here.
Useful stuff, particularly the style sheet guides.
WHAT WE NEED
But what we need is a more comprehensive user’s manual. An updated guide to the template tags; a guide to hacking (should that be plugin-ing?). The user’s manual should contain better instructions on both upgrading from previous versions, as well as detailed guides for importing from other blog systems. (‘Back up your database and run import-xx.php’ leaves something to be desired.) I do have several outlines for such a manual, but have been waiting for the software to stabilize a bit before proceeding. In retrospect, I’m not convinced that this was the best approach. The readme for 1.0.1-.0.2 could certainly stand to be updated in the interim.
We need volunteers to write formal documentation. A good first step for those interested is the docs mailing list, or you can contact me (see my profile for email address.) All that’s required is an ability to write reasonably well. It is not required that you be a WordPress guru, nor a coder. Neither Craig nor I were either (nor am I now) when we became co-leaders of the documentation effort. You just need to write. 🙂
I’d also like to see comments from users about what we need. I’m aware that many points have been made in the forums, but let’s start fresh here. I’d like to see specific requests and commentary about what’s weak and what works. Previous comments about the tone of the current docs have been noted (and mostly agreed with), so let’s not devolve into arguments over what constitutes humor. My primary interest is in producing documentation that is useful to both true newbies (which doesn’t assume knowledge; for example, that you know how to backup your database) and advanced users.
Let’s get started over here.