Re: Packages and documentation (was: [Call for Votes] XML_Statistics)

Having documentation is a good thing, expecting that each developer creates a full documentation that goes further than an API documentation is a good, but your comparison with the PHP source and its manual is flawed. I know that not all modules in PHP have been documented by the original author. Myself I have documented several modules, features, and I am not a contributor to that source code, just a user that learnt what the code did, got an account to help in the PHP Documentation team and wrote the documentation. And yes, I did have to read the .h and .c files to understand what those functions did, what is the problem with that? the suffering of one can be the benefit of many if the knowledge is shared. Anyone that groks enough a PEAR package and feels that documentation is lacking can do the same, get a PEAR Documentation CVS (if you already don't have one), donwload the XML DocBook, and add a the documentation that goes beyond the listing of an API. Just make sure that you talk to the package developer (I did that always when documenting someone else's code to make sure I got things right). Seems to me pointless to just point fingers (pun intended) to the developers for the lack of documentation, when the code and the documentation can easily be activities shared among the developer and the users of the package. I see no contradiction or problem there, just to coordinate with the author(s) and the will to do the writing. --- Katana <katana@katana-inc.com> wrote: > > Stop thinking of developers like yourself, and instead think of > > those newbies out there. There's two side to what PEAR does, helps > > the current sophisticated developers deploy code quickly, but also > > helps know-nothings like Johnny. > I totally agree with that... > As far as I was able to understand, PEAR was designed to provide a > repository of PHP extensions in order to add features that were not > implemented in PHP. You would NEVER tell someone "if you want to learn > about extension curl, go read comments in curl.c". > > A package without a documentation is almost like no package at all. > On the other hand, I don't think that a package should be refused > approval just because the documentation is not written yet. If the > author claims that he will write the documentation once the package is > approved, he should be trusted, otherwise, why give him a PEAR account > at all ? > > What about a rule stating that a package can not get the status stable > if there is no approved documentation ? > > Katana > > -- > PEAR Development Mailing List (http://pear.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > ===== -- Jesus M. Castagnetto (jcastagnetto@yahoo.com) Research: http://metallo.scripps.edu/ Personal: http://www.castagnetto.org/ PEAR stuff: http://pear.php.net/user/jmcastagnetto __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com