Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969379445 php.internals:40826
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain chiaraquartet.net from 208.83.222.18 cause and error)
Message-ID: <48E3CA24.6060805@chiaraquartet.net>
Date: Wed, 01 Oct 2008 14:06:12 -0500
User-Agent: Thunderbird 2.0.0.6 (Macintosh/20070807)
MIME-Version: 1.0
To: Elizabeth M Smith <auroraeosrose@gmail.com>
CC:  phpdoc@lists.php.net,  internals@lists.php.net
References: <7f3ed2c30810010639q445b94b3m637ed929215d1cc6@mail.gmail.com> <c0e7fa7f0810010707r724c089dv61bde6763b34898@mail.gmail.com> <49.5C.04812.F70B3E84@pb1.pair.com>
In-Reply-To: <49.5C.04812.F70B3E84@pb1.pair.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DOC] [DOC] Commit messages dead?
From: greg@chiaraquartet.net (Greg Beaver)

Elizabeth M Smith wrote:
> [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.

Hi,

I think Hannes was also talking about the fact that committers to CVS
are not using [DOC] in their commit messages.

I agree with Liz's appraisal of setting up docs for documenting.  This
could actually be solved with a minimal VMWare appliance that is
pre-setup with everything we need to do the docs (not sure how hard that
is to do).  VMware works great on windows and the version we would need
is free.

An online interface would be useful, but would it really occur to the
developers committing to php's cvs to use it?  I'm not so sure.  It
takes me almost as long, sometimes twice as long to document the things
that I write, this is the main problem from a coder's perspective: free
time.  I would almost rather have short summaries inside /* */ of how
things work close to the lines that implement them, it would make it
easier to debug other people's code as well as make documenting small
changes easier.  Big changes perhaps should be documented with either
quick README.DOCUMENTING files, or some other quick-and-dirty situation
in the source repo for those who are not yet comfortable in docbook, or
in English (as both native and non-native speakers can attest, it's hard
to translate PHP into English :).

This was done with namespaces, and it made documenting easier, right?

Greg