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.
A big +1.
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.
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. There has been various attemps made which need to be continued, one problem being that it seems whe have some fears to change the structure (or lack thereof) of the current docs.
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. Simplified syntaxes as wiki are good for small documents (i.e. a page) but IMO don't scale for large structured documentations.
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, providing template documents with style sheets that have to be used. These styles match the structure of the target XML document that is produced from the OO file. This solution just rocks, as anybody (even a boss :-) is able to write content in a userfriendly and productive environment with spell checking, typing completion, etc etc. On the CMS side, the sxw archive is exploded, the XML content is transformed into the target markup (e.g. DocBook) and images are stored.
Sure, for the Cocoon docs, we cannot wait to have a CMS setup and ready, or we'll never have docs ;-) What is rather simple, however, is to have some offline processing (based on the CLI) that would do the exploding/recomposition job to allow editing Cocoon docs with a real wordprocessor.
Yes, talking about technology rather than about writers, but IMO writers will come if they can use productive tools for the job.
WDYT?
Sylvain
-- Sylvain Wallez Anyware Technologies http://www.apache.org/~sylvain http://www.anyware-tech.com { XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
