cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Linden H van der (MI)" <H.vanderLin...@MI.unimaas.nl>
Subject RE: Planet Cocoon license and reuse of docs
Date Wed, 25 May 2005 13:49:12 GMT
> even a simple text editor. The one thing I have learned over the  
> years is that using the correct tool for the job makes the job  

True.

> Third, Cocoon's documentation is not as bad as people think. I was  
> able to put together a fairly complex e-commerce site that included  
> custom generators and transformers, made heavy use of flow, used  
> third party web services  and used several different types of  
> matchers among other sitemap tricks all from the documentation  
> available. Unfortunately I had to look long and hard to find what I  
> needed, but all I needed was there.

True. I've gone through this process myself. However, not much people
are willing to do this and therefore cry out for decent documentation
(i.e. everything in one place).

> Fourth, documentation just like code needs to be reviewed and 
> tested.  
> Someone other then the author needs to go through the tutorial or  
> article checking for facts, correctness and understandably.  
> Unfortunately, there are no unit tests for documentation. 

True.

> If you want to improve Cocoon's documentation you need to accept it  
> in various formats and have someone convert it to what it 
> needs to be  
> after appropriate vetting and editing. Forcing an editor or 
> format on  
> authors will only deter them from submitting their work. CMSs and  

Well, since there are no rules for documentation right now, everyone
wanting to write documentation is free to use whatever tool they like.
Sorry, but I haven't seen (apart from Upayavira and Ralph) anyone
posting "here's some documentation".

Either it's not done or it ends up in some nook or cranny of the
internet (blog, own website, whatever).

I do agree with your arguments but what you propose means we need a
setup that could pass for a publisher's office. This community has no
means to set up something like this and AFAIK no members that can do the
job. So, let's work with what we DO have.

Bye, Helma


Mime
View raw message