[wp-docs] New WordPress Handbook

[Tom Johnson]

I agree with the concerns Austin raised about the questionable benefit of
converting to Subversion rather than using a wiki format. I'm not even sure
how that would work. Each writer would need to check out a topic and then
check it back in, and then the whole thing would be compiled into a
book-like format? I haven't used Subversion before, so I'm unfamiliar with
it. If it requires too much ramping up to contribute, the contributions will
decrease.

I find the WordPress Codex a fascinating project, one that ideally I should
be actively contributing to but am not. My only contribution has been the
WordPress Quick Start Guide page,
http://codex.wordpress.org/WordPress_Quick_Start_Guide, which I felt was
sorely needed.

The technical communication community has made some progress in solving
problems that the Codex poses, but it goes a different route and employs a
technology called DITA (Darwin Information Typing Architecture). Ideally,
you would have a content management system based on the DITA architecture
that would enable multiple authors to create topics formatted in DITA that
could then be published in a variety of formats and deliverables. The CMS
would contain all topics. For a light guide, you would choose to include
only certain topics in your publication. But if you wanted to include it
all, you would map a table of contents including all topics. Additionally,
some companies are now creating DITA-to-wiki capabilities.

However, putting questions of technology aside, the larger problem with
WordPress' documentation is that, except for the recent screencast guy who
publishes release videos, the documentation effort seems to be mainly put in
the hands of the community. Isn't this a lot to ask of the community? I
think WordPress should hire a professional technical writer to manage the
entire project. I don't mean any disrepect to the documentation team with
this recommendation, only that this is too monumental of a task to leave
entirely up to the community to create and maintain.

Tom

http://idratherbewriting.com
http://twitter.com/tomjohnson


On Thu, Jan 22, 2009 at 11:12 AM, mrmist <listswpdocs at mist.org.uk> wrote:

> In message <4978841A.1040707 at santosj.name>, Jacob Santos <
> wordpress at santosj.name> writes
>
>> I had to laugh, because I have like 6 or 7 patches for WordPress which
>> haven't been committed yet and I'm still waiting. I also don't think you are
>> being sarcastic, which I mean you know, it actually isn't too easy to have
>> patches committed.
>>
>>
> Yeah that could be a concern really.  You only have to look at the
> wordpress trac, there's 340 tickets marked has-patch.  Some of them are 3
> years old.  If the manual goes that way it would get stale really quickly.
>
> Part of the beauty of the wiki codex is that changes have instant feedback.
> You see something wrong, you fix it. Done.  That's pretty gratifying.  It's
> much less gratifying to do something and then see it languish.
>
> --
> mrmist
>
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>



-- 
---------------------
cell: 801-822-2241
blog: www.idratherbewriting.com
twitter: www.twitter.com/tomjohnson
news: www.writerriver.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://comox.textdrive.com/pipermail/wp-docs/attachments/20090122/2309cb25/attachment-0001.htm