Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Message-ID: <40DCB81D.2070100@gmx.de>
Date: Sat, 26 Jun 2004 01:41:17 +0200
From: Joerg Heinicke <joerg.heinicke@gmx.de>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.7) Gecko/20040616
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [RT] The Cocoon Handbook
References: <40DAA2D2.8000905@umn.edu> <40DC018B.1080806@apache.org>
In-Reply-To: <40DC018B.1080806@apache.org>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Ok, after I have shoot on most of the proposals I guess I must provide 
better alternatives :) My two alternatives for "large structured 
documentations" already have been mentioned: DocBook and Open Office.

>> >> 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.
> 
> A big +1.

I also like the DocBook way very much, we did it that way at Virbus. 
Customer requirement specifications and other documents were written 
using DocBook and transformed using customized DocBook stylesheets into 
Virbus CI PDFs.

> There are two main problems that IMO explain the poor state of Cocoon docs.
> 
> The first one is that Cocoon being a large beast, it's doc has to be 
> large, and therefore needs a well-defined structure.

Again my pointer on Helma's TOC effort: 
http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC. It's a good 
starting point IMO.

> The second one is that writing docs in XML is a major PITA, futhermore 
> when we have fancy word processors just a click away on our computers. 
> I'm sure that it refrains many prople from writing docs (including me). 
> Intermediate tools like XXE ease the job, but aren't as userfriendly as 
> good old MS Word.

We did it the XXE way at Virbus, it works really good, but it's of 
course a developer's way, not a documentor's way.

> Simplified syntaxes as wiki are good for small 
> documents (i.e. a page) but IMO don't scale for large structured 
> documentations.

Yes, Wiki and HTML just can not work IMO. There is no editor available 
for writing documentation with them. It starts with internal linking, 
goes on with loose structure and ends with ... I don't know :)

> Now we have that nice thing called OpenOffice that is a wordprocessor 
> storing its content as XML in a zip archive. We've used it as a 
> front-end for a CMS

We too, but at a very low level.

> WDYT?

I can live with both OO and DocBook. While the latter one is really 
straight forward for us, we will probably not really attract 
documentors, even with some fancy editors like XXE as the usability is 
not as good as with OO. But maybe that's only because the documentor 
must have the document structure in mind.

With OO it is much more difficult for us to process the results. The 
documents are loose structured in the same way as HTML (no tree), but in 
contrary to HTML there is at least support for requirements like 
internal linking. A stylesheet processing those documents and adding the 
structure will be really hard (massive Muenchian Grouping), but not 
impossible of course. Therefore it's much easier for the documentor. I 
would be interested how you did the templates, Sylvain, to see if this 
solves problems of the post processing.

The fact that OO files are not straight XML, but zipped XML, I would 
ignore. It's easy for us to do zip/unzip automatically. We only must not 
store the binaries in CVS, otherwise we will loose the possibility of 
doing diffs in CVS. Ah, when writing this another advantage of XXE come 
to my mind: a diff on OO files probably does not make much sense, as 
they store the XML unformatted. XXE indents and formats the XML nicely 
on save.

Joerg