cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benjamin Boksa <mailingli...@boksa.de>
Subject Re: Documentation System [was: Spring Configurator Docs]
Date Thu, 12 Feb 2009 16:24:48 GMT
>> I did some "documentation port" myself, but I have to admit it is  
>> not that easy, since something *may* indeed have changed in the  
>> passage... bottom line: you have to know a component's behaviour in  
>> both 2.1 and 2.2 before safely porting its doc.
> You're so right about that.  It is a big job.
>
> I started updating the HTMLSerializer [1] but then realized there  
> were actually two implementations of it with different sets of  
> parameters.  Not only that but a lot of 'folklore' and list wisdom  
> was trapped in the mailing list and on the old wiki over the last  
> few years and that needed to be set free.

I hope it is OK if I jump into this discussion - during the recent  
months I have been working with Cocoon 2.2 a lot - it is really hard  
to find documentation about some of the "advanced" features - and it  
is even harder if some information are simply wrong (because they are  
not up to date). I know I have not done my duty and corrected these  
errors :-(

During some spare minutes (running, driving) I thought about about  
possible ways to improve the documentation. On some blogs ([1], [2]) I  
have found a lot of interesting (and quite accurate) information which  
I could not find on the official cocoon page. I liked the HOWTO- 
approach which imho is missing for many features (e.g. ("HOWTO  
configure authentication")). The bits and pieces are there and  
documented but I often miss the "red line" (hope I can say that in  
english).

As there is no official cocoon blog as far as I know I think such a  
blog would be a good way (in addition to the existing documentation) to

a) publish HOWTOs that do not fit into the source documentation
b) publish articles that aggregate information from the existing  
documentation/link to them
c) link to other interesting articles from outside (which might  
motivate some people to write about cocoon to get some traffic from  
the official blog)
d) inform about updates
e) inform of other cocoon/apache-related events

What is published there could be revised by some developers before  
publishing and people from outside can easily contribute stuff.  
Commenting would also allow to improve possible published best  
practices… Tagging would allow to structure information…

Just my two cents - thanks for reading this,

Benjamin

[1] http://mrhaki.blogspot.com/search/label/Cocoon
[2] http://happygiraffe.net/blog/tag/cocoon/
Mime
View raw message