Re: PEAR Guide/Docs

le 27/03/03 11:42, Ant-1 à ant-1@ccedille.org a écrit : > 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. Hi Antoine, I agree with your ideas. It would really be cool if a team could write some docs on the packages that are released when they are released. I also think it is really strategic to have proper documentation. I've tried for the fourth time to get my hand on Docbook XML and PEARDOC. Now, I think all this is just a piece of shit. It made me loose many hours just to write some ugly documentation. Some say XML is good because it separates layout from content but with Docbook and Peardoc, you have to think layout all the time, which page go where, how to link between this and that, will this piece of code look good... So my conclusion is that I am not going to write any docs for my packages as long as there is no proper tool to write it. It already takes enough time to add code comments PHPdoc style. I might write documentation some day but certainly not with docbook. A web frontend or a GTK app would make it for me. I don't want to install openjade or whatever DTD that will take Mb on my disk just to write a few lines of text. This is silly. Why make it simple when it can be made the hard way ? Bertrand Mansion Mamasam