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
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
