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 have the same complaint, and this is why I still end up writing a lot of my own library code rather than trying to apply a pear library to my projects. Pear::DB has a good tutorial and has had for quite a while, but do any of the other packages?
Personally I'd like to see a package can only be beta status if it has the api documentation complete and online, and can only be stable status if it also has a tutorial and usage examples.
Hopefully this would encourage developers to give priority to documentation over new features. That would bring in new users, who discover bugs improving software quality; and some percentage of them would end up developing extensions so the new features would come as well.
Darren