Although never ever putting it this well, this was my intention when I started on the TOC for 2.15. Unfortunately things got too hectic here to keep the pace going, but it's not forgotten. I want to chip in, but my time is very limited at the moment and my knowledge of Cocoon is not that big that I could write much nor even judge is some documentation is worth keeping. For the rest: if my help is needed I'll see what I can do.
Bye, Helma > -----Original Message----- > From: Tony Collen [mailto:[EMAIL PROTECTED] > Sent: Thursday, 24 June 2004 11:46 > To: [EMAIL PROTECTED] > Subject: [RT] The Cocoon Handbook > > > This is a late-night, rambling [RT]. I think it's a good > idea. You may or may > not. Please flame, argue, discuss, rant, etc... it's an > [RT], after all... > Have fun! > > >> The Problem: Documentation << > Right here is where I would discuss the problem in a more > in-depth sort of way, > but since my brain is pretty much shut down, that's not going > to happen. Insert > your own rambling explanation of why the docs stink. ;) > > >> The Solution << > I propose we create a free, high-quality electronic book (entitled > _The_Cocoon_Handbook_), which will eventually replace the > mess of docs we > currently have. It will be in DocBook (possibly simplified) format. > > Not only are we having a hard enough time keeping the > documentation up-to-date > normally, fightning the rampant wiki spamming has become > almost a full-time job > as it is. > > We can integrate the eventual book with user-added notations, > similar to how PHP > lets people log in and annotate the existing docs. > > >> Considerations << > There are several things we need to take into consideration. > In no particular > order, they seem to be: > > - The existing documentation. > How can we take advantage of what we already have? > Further, how can we lose > the crap and keep the good stuff? > > - Forrest. > How will it affect this plan, if at all? > > - The Wiki. > We need to be able to allow people to annotate or refine > the docs with ease. > How can this be done? > > IMO there are two separate things that need to happen with > the docs. One is > annotating the docs, adding user comments, etc, just like the > PHP docs. The > other is to actually maintain the docs which are being > annotated. That is, if a > new component comes out, or a feature is added, to change the > actual DocBook > source. If someone is willing to help maintain the docs > (although might not be > all that experienced of a Cocoon user), we should be willing > to let them become > a committer in order to maintain the docs. > > That's about all that my brain can spew out for now. I > really think this is a > good idea, and I've been throwing the idea around in my head > for a while now. > > Regards, > > Tony >
