cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
Subject Re: [RT] The Cocoon Handbook
Date Thu, 24 Jun 2004 14:08:19 GMT
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), 
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.


Nicola Ken Barozzi         
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)

View raw message