cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From H.vanderLin...@MI.unimaas.nl
Subject RE: [RT] The Cocoon Handbook
Date Thu, 24 Jun 2004 11:33:04 GMT
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:colle006@umn.edu] 
> Sent: Thursday, 24 June 2004 11:46
> To: dev@cocoon.apache.org
> 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
> 

Mime
View raw message