Re: PEAR Guide/Docs

Le jeu 27/03/2003 à 06:18, Gunther a écrit : > After using PEAR for a while, I still find that whenever I like to use a new > functionality I have to start a research project to find proper > documentation/information. Most of the time only the functions are > explained, but not how they should be used together. I just had to start > again a 'project' for DB transactions. And again I have to read the PEAR php > source code for PEAR DB to actually understand how I should use the > functions and how they are named. I totaly agree with Gunther. I will give you my point of view here, which is the one of an experienced PHP coder trying to get the most of reusability, and concerned about PEAR. I first noticed PEAR one year ago, and am only for a few weeks using some PEAR classes in my code. Why ? Because not many things are properly documented. And I don't mean PHPdoc here. I mean usage guidelines, that Gunther ask for when talking about "Error handling with PEAR" and other guides. I know the developpers' mantra UTSL, but I always thought it useful for the first ring of developers, the pioneers. These ones are attracted by new things and will always find their way through a messy code and use it properly for their own concerns. And become a contributor. But PEAR must go beyond that first ring (and has already began to do so, hopefully). The second ring is made of people who knows that reusability is a key factor, who knows that around a language there is always the pioneers ring that tried to develop utility code they can pick up for their projects, who are willing to send back contributions, in the form of bug fixes and even packages when they discover they made one that can be integrated because it's missing. This second ring, the settlers, is the most important in terms of adoption and maturity, because : - they are more numerous than the pioneers - they have an "external view" that helps sorting things out - they are the interface beetween the pioneers and the outer circles of developpers. No settlers, no immigrants (the third circle). IMHO, PEAR is taking off now. And I love it. But this documentation issue will do the difference beetween a crash and a proper community adoption. Without doc, we will always need the help of pioneers to use the code, and at some point in the community growth they won't be able to help everybody and will burst into flammes. Without doc, the settlers won't settle, and will turn to another language. Without doc, the outer rings won't bite. Without doc, PHP can become a "useful little scripting language for personal pages". Documentation falls into several categories : - Coding guidelines : these one are written but could benefit from some additions, which can be taken from java naming standards or whatever - PEAR Package writting guidelines - Documentation guidelines : how to write a package's doc. - PEAR evangelism basics (useful for settlers to obtain from their managers authorization to use PEAR) A package's doc should include : - Analysis diagrams (classes diagrams, ...) for big packages - PHPdoc : properly commented code will generate it. - Tutorial and examples OK, we know that not every package creator/maintainer will have enough time/ability to do all that. So there should be a documentation team (maybe it exists, I didn't checked PEAR-DOC ML/newsgroup) like the PHP team leaded by Stig. And that team wonn't let a package be released as stable when doc is missing. And documentation should live on pear.php.net for convinience. I know there are efforts made by pioneers to build such a framework, and that subjects like these will be debated in Amsterdam soon (PFCs, PEARWeb, quantity vs quality), and I look forward to the results of this meeting (which I will attend by IRC). Last note : don't get me wrong, I'm a gret PEAR fan, and would like to help in the organizational matters, which I believe is the most important subject when dealing with a community. Cheers, Antoine Pouch