cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylv...@apache.org>
Subject Re: [RT] The Cocoon Handbook
Date Fri, 25 Jun 2004 10:42:19 GMT
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 }


Mime
View raw message