Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Date: Thu, 24 Jun 2004 17:35:40 +0300 (EEST)
From: gounis@osmosis.gr
To: dev@cocoon.apache.org
Subject: Re: [RT] The Cocoon Handbook
In-Reply-To: <cben9o$72i$1@sea.gmane.org>
Message-ID: <Pine.LNX.4.44.0406241733250.17569-100000@zeus.osmosis.gr>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII

On Thu, 24 Jun 2004, Nicola Ken Barozzi wrote:

> Tony Collen wrote:
> ...
> >  >> 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.
> ...
> 
> Let's not make this a technology issue, it's a "people" issue.
> IOW, it's not (only) the doc system that sucks, but it's the doc writers 
> that are missing.
> 
> 1 - The first thing we need IMNSHO is to define a structure of this 
> book: The sections, the chapters.
> 
> 2 - Then we can take the existing docs and put them into place in this 
> structure till there are no more, eventually enlarging the structure to 
> make them get in.
> 
> 3 - Finally, we need to fill in the missing gaps. Only at this point do 
> we really need an easier documentation system ala DOCO.
> 
> What I would suggest doing is to make a new documentation directory from 
> Forrest and fill in the tabs.xml and site.xml files (step 1). The copy 
> the docs from the current documentation and link them in the site.xml 
> file (step 2).
> 
> [Note that at this point we should be using SVN, and users can then be 
> given fine grained access only to the docs even without having a Unix 
> account. In this way we can give away SVN access just for documenters 
> that don't need to become part of the project.]
> 
> I would also suggest to use simple html files (that Forrest can read), 

why not xhtml that are structured?

using a simple subset of xhmtl tags will be easy to tranform to PDF

-- stavros

> so that users can use any editor to create them without running Forrest, 
> and they can be seen also in ViewCVS too.
> 
> What I can help to do is to set up the initial Forrest doc space in the 
> Cocoon CVS where this can start happening.
> 
> WDOT?
> 
>