Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:40823
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Message-ID: <49.5C.04812.F70B3E84@pb1.pair.com>
To: phpdoc@lists.php.net,internals@lists.php.net
Date: Wed, 01 Oct 2008 13:17:21 -0400
User-Agent: Thunderbird 2.0.0.17 (Windows/20080914)
MIME-Version: 1.0
References: <7f3ed2c30810010639q445b94b3m637ed929215d1cc6@mail.gmail.com> <c0e7fa7f0810010707r724c089dv61bde6763b34898@mail.gmail.com>
In-Reply-To: <c0e7fa7f0810010707r724c089dv61bde6763b34898@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DOC] [DOC] Commit messages dead?
From: auroraeosrose@gmail.com (Elizabeth M Smith)

[snip]

> Many of us - 'documentors' -  (if not all) are programmers and used to use
> CVS and other versioning system. But this takes some extra time that IMHO it
> shouldn't. If you want to "spread the word" and get lots of people to help
> in docs, I believe this kind of thing that Launchpad uses is a go. I'm very
> well aware that this takes time and not every contributor may actually help
> with good docs, but it could be moderated.

[snip]

100% yes - the initial hurtle to getting new people writing docs is
teaching them docbook and cvs.  You can whine all you want about "how
easy it is" - but it is NOT a zero learning curve and there are no good
(free) docbook tools on the systems most people use on the desktop (yes,
I mean Windows - and no people are not going to switch OS's for docbook
tools).  Writing in XML is not a natural thing.  An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)
However...you will have to wade through the bad docs too.  And I have no
solution for dealing with the "three million tools" issues.

Thanks,
Elizabeth Smith