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.
I think this should be part of the wiki. Each package will have its own wiki area. Those requisites could be use for the base template.
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).
Indeed.
Arnaud.