Documentation

[El Zagna]

One of the common complaints about PEAR is the lack of documentation on many of the packages.

I would like to propose that before a package can be considered "stable" that its documentation meet some minimum threshold of adequacy. In particular I would like to see a requirement that each package have a clear statement of its purpose. This could be something as simple as a sentence that starts with "The purpose of this package is to...".

[mark]

[El Zagna]

Well, of course a "minimum threshold of adequacy" is going to be a pretty subjective standard. Perhaps you can point me to the actual language for the required documentation.

Even so that doesn't address the statement of purpose issue. I realize that there is a "summary" and "description" required by each package, but all to often these get tripped up on the common problem of saying what the package does not why it exists.

[mark]

Let's keep this discussion at one place. I saw that you've opened a bug report ...
(an email to pear-dev would have been better IMHO, BTW)

[El Zagna]

Yeah, I realize that. The thing is I'm not sure who's looking at what, and which sites are actually active. If it's better to have the discussion elsewhere let's close this one down.

But really, this is pretty typical of the problems I've had with PEAR. The entire set up - the whole infrastructure if you will - strikes me as being hopelessly disorganized.

Right now I'm trying to decide on which technologies I need to focus on for my own marketability. Probably all of us are doing that to one degree or another. I thought that the basic concept behind PEAR was excellent, so I was willing to spend some time test driving it. Unfortunately the productivity bang for the buck has been pitiful.

It's a shame, really. I think that buried somewhere in that jungle of poor usability is some real gold, but man, oh, man, I don't think I've got the strength to get to it.