cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Collen <colle...@umn.edu>
Subject [RT] The Cocoon Handbook
Date Thu, 24 Jun 2004 09:45:54 GMT
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

Mime
View raw message