Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969379453 php.internals:40837
Return-Path: <philip@roshambo.org>
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Delivered-To: mailing list internals@lists.php.net
Received: (qmail 69372 invoked from network); 2 Oct 2008 08:55:36 -0000
Received: from unknown (HELO lists.php.net) (127.0.0.1)
  by localhost with SMTP; 2 Oct 2008 08:55:36 -0000
Authentication-Results: pb1.pair.com header.from=philip@roshambo.org; sender-id=unknown
Authentication-Results: pb1.pair.com smtp.mail=philip@roshambo.org; spf=permerror; sender-id=unknown
Received-SPF: error (pb1.pair.com: domain roshambo.org from 207.210.105.50 cause and error)
X-PHP-List-Original-Sender: philip@roshambo.org
X-Host-Fingerprint: 207.210.105.50 analucia.asmallorange.com  
Received: from [207.210.105.50] ([207.210.105.50:34660] helo=analucia.asmallorange.com)
	by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP
	id 5A/64-39275-78C84E84 for <internals@lists.php.net>; Thu, 02 Oct 2008 04:55:35 -0400
Received: from c-67-183-231-13.hsd1.wa.comcast.net ([67.183.231.13]:55184 helo=[192.168.0.199])
	by analucia.asmallorange.com with esmtpa (Exim 4.69)
	(envelope-from <philip@roshambo.org>)
	id 1KlJy6-00054g-OS; Thu, 02 Oct 2008 04:55:30 -0400
Cc: "Stanislav Malyshev" <stas@zend.com>,
 "Elizabeth M Smith" <auroraeosrose@gmail.com>,
 phpdoc@lists.php.net,
 internals@lists.php.net
Message-ID: <CA9C9E02-768C-424F-9A56-B0BC5AF0C1C8@roshambo.org>
To: Hannes Magnusson <hannes.magnusson@gmail.com>
In-Reply-To: <7f3ed2c30810011206o69bf2b25h2ec38df8ffe5e47f@mail.gmail.com>
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v929.2)
Date: Thu, 2 Oct 2008 01:55:27 -0700
References: <7f3ed2c30810010639q445b94b3m637ed929215d1cc6@mail.gmail.com> <c0e7fa7f0810010707r724c089dv61bde6763b34898@mail.gmail.com> <49.5C.04812.F70B3E84@pb1.pair.com> <48E3BB65.9040405@zend.com> <7f3ed2c30810011206o69bf2b25h2ec38df8ffe5e47f@mail.gmail.com>
X-Mailer: Apple Mail (2.929.2)
X-AntiAbuse: This header was added to track abuse, please include it with any abuse report
X-AntiAbuse: Primary Hostname - analucia.asmallorange.com
X-AntiAbuse: Original Domain - lists.php.net
X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12]
X-AntiAbuse: Sender Address Domain - roshambo.org
X-Source: 
X-Source-Args: 
X-Source-Dir: 
Subject: Re: Commit messages dead?
From: philip@roshambo.org (Philip Olson)


Hello all,

An online editing mechanism was discussed and started[1] but let's be  
honest here and stare at the larger problem. The documentation team is  
on extended holiday and why? I don't know... maybe it's cyclical? Or  
maybe we need a larger marketing budget. But really if making it  
easier to inject words into the manual is seen as the main problem  
here then great, that sounds easy to fix, but writing good  
documentation is time consuming and I guess many humans prefer not  
doing it at all even though it's an art too. But maybe removing the "I  
don't have time to setup/test yet another tool chain" excuse is a good  
start. The new doc build system has gone a long way to do this.

We recently reviewed the doc TODO situation and one of the first tasks  
is streamlining the HOWTO because it's a bit lengthy and dated. As for  
the required tool chain it's not too difficult anymore, and DocBook  
knowledge and special tools are not needed except to know XML <para>  
is like a <p> in HTML. Basically. Almost.

The online editor thread with demo:
   [1] http://markmail.org/message/xchvvhk4hlvg33a3

Regards,
Philip