Re: Package Abstracts

On Tue, 2004-11-16 at 20:48, Arnaud Limbourg wrote: > > 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. I agree with Arnaud. > > 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. This is a fairly big job yes, which I will most likely take upon my self, since I've had this wiki idea stuck in my head since I and Arnaud were looking at some apps together to being able to orginize LiveUser much better, and we came upon http://projects.edgewall.com/trac/ which is a great piece of software, has few drawbacks, but surly the basic idea is great, and I'm pretty sure that when Arnaud mentioned wiki he had something very similar as my ideas :) Maybe I even can poke Arnaud to help with this ? (*pokes arnaud*) Of course like said before, this is a huuuuge task, so it won't be ready anytime soon, and hasn't been started as of now, more thought has to be put into it, and what the wiki should be capable of and etc. i.e. planing. Any ideas for this people ? :) Every idea will be considered so don't be shy! ;) Regards Helgi