Package Abstracts

This is a follow up on the "Documentation" discussion (and is probably in the wrong list, but since the discussion started here...) After manning the booth at our LinuxWorld stand and spending a good amount of time hanging around the booth at IPC2k4, I would like to propose that we create a simple format of the "mini-documentation" of EACH package. This documentation would not be comprehensive, but would be well written and provide an overview of what each package does. A good example is Perl's documentation which requires the following 5 sections: Name Abstract Synopsis Description Notes and Bugs I would propose that this documentation be maintained along with the packages, and updated to be included and installed in the docs/ folder with each release. This is a fairly big job, but I think that the effort will be well worth the trouble, and will give PEAR a much more user-friendly face to the world (and put an end to the "PEAR is poorly documented" mantra we hear so often). Getting back to the conferences, if we could come up with a format, we could design a simple PDF which contains one-page descriptions of many of the most popular packages. Something that cannot be done with the current manual. I have been thinking about this for a while, and am very open for suggestions or ideas about how we can make something like this work. Aaron