>> 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
