Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Message-ID: <40DABA1E.3000109@upaya.co.uk>
Date: Thu, 24 Jun 2004 12:25:18 +0100
From: Upayavira <uv@upaya.co.uk>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.4) Gecko/20030624
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [RT] The Cocoon Handbook
References: <40DAA2D2.8000905@umn.edu>
In-Reply-To: <40DAA2D2.8000905@umn.edu>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Tony,

I think I'd say simply that Cocoon operates as a 'do-ocracy'. He who 
does, chooses (usually!). It is widely accepted that something needs to 
happen on the docs. And really, what it is going to take is someone just 
getting on and doing it. I suspect that someone putting in the legwork 
would get a lot of support from the rest of us. That is the missing 
component, not the ideas. Are you offering? ;-)

Regards, Upayavira


Tony Collen wrote:

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