Re: On PEAR quality issues and natural selection

On Apr 9, 2004, at 5:49 PM, Martin Jansen wrote:

On Fri Apr 09, 2004 at 10:0948AM -0500, Richard York wrote:

Documentation on documentation is another lacking area of PEAR, there's a link to the docbook website, but no explaination of how to write the bloody documentation, nor of how to access CVS and place it in CVS. You can get a CVS account, but no explaination of how to use it. No examples of well formed docbook xml, PHPDcoumentor is good, but its not PHPDocumentors job to explain how to add code snippets and tables and all that.

The lack of documentation is surely a problem. But (this may sound like a cheap excuse now) there is about nobody who has enough time to write all the necessary documentation. So if there is anybody, who wants to make the world a better place, please get in touch with pear-doc@lists.php.net.

I have worked with some developers, trying to help with the missing documentation. (Please note, I did some work but much less then what I promised/wanted to do and I am really sorry about that). The Docs format might be a problem (aka you need to spend some time to learn it) but I also noticed that some developers host the full and detailed documentation on their own site. Is this allowed ? They do link the documentation to the package listing/description. In such a case, it might be kind of confusing to keep 2 different documentation synchronized. Just a proposal: We could have a set of XML template documents with a clear how-to for developers. This might help if the developers are serious on writing some good documentation. Thanks David Costa