[wp-docs] Handbooks

[Jane Wells]

Hi everyone. At WordCamp San Francisco at the end of May, Matt  
Mullenweg announced a documentation project that would create a series  
of WordPress handbooks that would complement the Codex. The idea is  
that the Codex, in wiki form, has become difficult to manage, makes it  
hard to find information because there's just so much there, and is  
intimidating to users who are looking for a little guidance and  
instead get a firehose of technical info and links to other articles.  
Inspired by the SVN handbook at http://svnbook.red-bean.com/ the  
WordPress Handbooks are meant to be HTML documents editorially  
controlled/curated using Subversion. Lorelle posted to this list about  
it in January (archive: http://comox.textdrive.com/pipermail/wp-docs/2009-January/001862.html 
  ) and it's come up a few times in dev chats and such, so the idea  
shouldn't be too out of the blue.

The plan is to have a handbook for each version (2.7, 2.8, 2.9, etc),  
so instead of using the Codex method of continually updating changes  
and having additional pages dedicated to changes by version (which  
invariably miss a few things), we'll have entire handbooks archived  
for each version of WordPress, with the most current information  
always being "in trunk," just like WordPress itself. In addition,  
handbooks will be available for several types of users: End Users,  
Theme Developers, Plugin Developers, Sys Admins, and CMS users.

The End User Handbook will be the most basic, and will focus on how to  
set up WordPress, use the admin interface, and interact (on a very  
basic level) with theme files and plugins. We wrote a draft of this  
handbook with the release of 2.7 (you'll recognize many chunks of text  
taken from the Codex, as well as original text that describes the then- 
new features), and earlier this year Nikolay Bachiyski took on the  
task of turning it into a repository-ready coded version and setting  
up a Trac to handle patch submission (for suggested text changes).  
It's pretty rough, needs some love re formatting and needs to get a  
once-over for voice and features that have changed since 2.7, but you  
can take a look at it here: http://wordpress.org/docs/
The Trac is here:  http://docs.trac.wordpress.org/ though you'll see  
we haven't started using it yet.

Currently it is just a single HTML file. Once it's up to date and  
pretty, the plan is to a) get the end user handbook included in the WP  
core download and link to sections of it from the help tab (and/ or  
display text there, hopefully), and b) make it possible to print a  
nice PDF of the handbook for those who like to have a printed page  
sitting next to them on their desk while they're learning how to use  
applications.

In the coming week I'll be posting a ticket to the trac for text  
changes to describe the widget redesign stuff, which is already  
written but needs to be added. I'll screencast the process of  
submitting a patch to the handbook and post it to wordpress.tv so  
everyone can see how it's meant to work. Note: you don't need to learn  
Subversion to submit patches! You'd just attach your text to your trac  
ticket (or include it in the trac comment). Only people with commit  
access would need to know Subversion (commit process TBD due to coding  
requirements, etc).

So, what happens next to get this off the ground? As a first step, I'd  
like to assign an editor or two for each of the handbooks (end user,  
theme developer, plugin developer, etc) who will take responsibility  
for collecting the appropriate Codex information and/or writing/ 
gathering new text as needed for first drafts. I'll stay with the end  
user handbook (since I work with the core devs to determine the new  
features, I have access to info early in the dev cycle), and will do  
the once-over for voice consistency so there's a good example before  
people get started, but would like a co-editor to work with moving  
forward. I've also got a volunteer writer/editor, Doug Provencio,  
who's started on an outline for the CMS User Handbook. So for editors  
I'd like to round up someone to work on end user, someone to work with  
Doug on CMS, and 1-2 people each for the theme developer, plugin  
developer and sys admin versions. Editors should be able to create a  
good outline, have excellent writing skills, and be familiar enough  
with the Codex to easily mine it for existing text.

As we assign volunteer editors, I want to start regular IRC chats  
during the first phase of the project, so that more community members  
can advise on what should go into each handbook, review outlines, etc.  
We'll also have a blog set up at http://wphandbook.wordpress.com/ for  
progress reports, questions, asynchronous brainstorming, etc. I'll add  
editors as authors, and it will allow comments from anyone. This list  
will probably be home to chunk of discussion as well.

I'll be posting on the dev blog with this information tomorrow or the  
next day, but wanted to give you, the current documentation crew, the  
word first. It's my hope that having a handful of people working on  
handbooks won't result in an exodus from Codex contribution... the  
Codex is still the definitive living documentation for WordPress, and  
deserves as much love as it can get. That said, I'd love to get  
handbook contributors who are experienced with the Codex. :)

If anyone wants to volunteer as an editor (and can make a commitment  
to work on it over the next couple of months until the final draft is  
out there and available for patching), please email me offlist. For  
general discussion around how to approach the handbook project in  
general, reply to list.

Thanks!
Jane