Re: Random Thoughts About Pear-Doc
| From: | Daniel Convissor | 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