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