The next version of WordPress will have support for user-defined themes built in. Until now, WordPress used index.php and the comments-files in conjunction with a CSS stylesheet, to control the way it presented the content when published. All other pages, including the category and archive pages were actually generated by passing parameters to the index.php page. The introduction of the theme system does not mean that the old method of styling papges will not work. If you are upgrading from v1.2 or v1.2.1, users have the liberty to continue using their existing design, without switching to the new system. The new Theme system will provide a method for you to define different physical (.php) files for the different components of your weblog. Let us call each of the different physical *.php files a template. So, with the new theme system, you can define different templates for the category archives, the monthly archives, the individual-entry pages etc.

If, as a designer, WordPress user, or developer, you want to get a head start in creating themes, please visit the Theme Development page at the wiki. Now would be a good time to bring any concerns or suggestions you may have regarding the Theme System. You can leave comments at the Theme Development Discussion Page, or discuss it in the hackers mailing list or the beta discussion forum.

Please feel free to improve the pages at the wiki, they are all yours!

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.