Re: Random Thoughts About Pear-Doc

From: Date: Fri, 16 Apr 2004 17:02:31 +0000
Subject: Re: Random Thoughts About Pear-Doc
References: 1 2 3 4 5 6 7  Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3550@lists.php.net to get a copy of this message
On Wed, Apr 14, 2004 at 04:43:59PM -0500, Paul M Jones wrote: > However, I think the doc system must become more dynamic, with a much > shorter feedback loop, and significantly lower barriers to entry. While the shorter feedback loop seems to have a priority like "it would be nice," it turns out the priority is "really important." A quick turnaround means people writing the docs would be able to submit and validate their changes (as well as viewing how they look in the live manual) without having to go through the hastle of installing the build/validation tools on their own computers. Installing these tools seems to me to be THE biggest impediment to the PEAR docs. Writing DocBook really isn't THAT hard, especially considering several steps have been taken this week to better explain the peardoc process. Martin has written a new primer on writing documentation, peardoc/en/guide/developers/documentation.xml, to which I've added further helpful information. Also, in peardoc/en/chapters, contributing.xml and faq.xml have been edited to ask for help with documenting and translating, as well as providing links to the appropriate resources needed to do so. I have enhanced the sample DocBook files in peardoc/en/authoring. They can be used both to start out new documentation by copying the entire files then editing them and to aid in cleaning up existing documentation. Finally, I have completely overhauled the DB docs so they can be a real world example of how to write PEAR docs in DocBook XML. All of this will show up in the next doc build on Sunday. If anyone has ideas how to improve any these resources, please speak up, or better yet, start committing. http://cvs.php.net/cvs.php/peardoc/en/guide/developers/documentation.xml http://cvs.php.net/cvs.php/peardoc/en/chapters/faq.xml http://cvs.php.net/cvs.php/peardoc/en/chapters/contributing.xml http://cvs.php.net/cvs.php/peardoc/en/authoring/ http://cvs.php.net/cvs.php/peardoc/en/package/database/db/ > I think the doc system must become more like a web-based application, > not a CVS repository that must be compiled from time to time ... snip ... > But a web-based app it must be. I disagree. > I think that a wiki-like system would present several advantages, > including live comments Having comments is a good idea. This can be added to the existing system fairly easily. > I do not think PEAR Group, PEAR Core, or PEAR Dev are ready, willing, > or able to make radical changes to pearweb, either now or in the next > 12 months. That's not the impression I get. Thanks, --Dan -- T H E A N A L Y S I S A N D S O L U T I O N S C O M P A N Y data intensive web and database programming http://www.AnalysisAndSolutions.com/ 4015 7th Ave #4, Brooklyn NY 11232 v: 718-854-0335 f: 718-854-0409

« previous php.pear.doc (#3550) next »