Re: Packages and documentation

Daniel Khan wrote:

Joshua Eichorn wrote: [..]

I think what he is saying is PEAR has a bad reputation and the reason isn't because of the quality of the code (at least not in most cases) but the quality of the documentation and surrounding infrastructure.

Where, what, why? Reputation: Does it really have a bad reputation? Ask around, its quite obvious

Infrastructure: What do you mean? How could we improve this? Try using PEAR on windows, or the fact that in most php installs the PEAR that you get with it is horribly broken (i think this is fixed in 4.3.3 but i've been installing with --without-pear for to long to know)

Documentation: Right - many packages haven't a nice documentation but all packages I used yet provided at least a nice example. There is some decent documentation, and many packages have inline docs (http://phpdorks.net/docs/api/pear/).

But there are still lots of problems and only a few people who try to fix them.

Yes documentation is important and we don't have to discuss that again as documentation is required by rule. IMHO everybody developing for PEAR, including me, knows that it's very important. So as time is short the only thing we could do is to provide examples and short readme's keeping in mind that we _have_ to do the documentation ASAP. This seems reasonable to me, maybe we should go the same route here as the php Manual where even on documented elements are show in the manual, they just have a note that they need to be documented, (using phpDocumentors peardoc2 converter we would be close to this)

When a package moves into PEAR the work isn't finished. There are feature requests, API changes, bug fixes, improvements,... So we can't always sit back and doing documentation work. Most of us have daytime jobs and some even have family. It needs much time management to do open source development so sometimes things aren't as they should be... I agree totatlly here and i think having to have documentation to have your package accepted is a bit much, but i don't see how at least have a section in the manual with those basic examples is to much to have before marking a package stable. (removing already stable packages doesn't make much sense).

just my 2 cents Daniel Khan I really don't think having your package documented should be hold over anyone with penality of death, but i also don't think we should be attacking people who are trying to think of ways to make things better. We all know we need more documentation, and we also all know people don't work full time on PEAR, but always using that as an excuse gets old.

We should at least be moving towards minimum levels of documentation where every stable package has a section in the manual even if it only includes the undocumented api. just my 2 cents -joshua eichorn