cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Legg <david.l...@searchevent.co.uk>
Subject Documentation System [was: Spring Configurator Docs]
Date Thu, 12 Feb 2009 13:36:00 GMT
Hi Luca,

>> Also it might have seemed like a brilliant idea to extract 
>> documentation directly out of the code but that actually adds a 
>> further barrier to getting it done as you are then faced with 
>> updating the code when all you wanted to do was write about it.
>
> One has to choose the lesser of two evils: steeper learning curve vs 
> probable de-synchronization of docs from the actual code... I'd say 
> the former is the less harmful.

I *was* going to  respond by listing all the pages which currently say 
"No documentation available yet" e.g. [1].  But as I started I realized 
you were right :-)

I can see now that automatically lifting information out of the code 
has, if anything, saved the docs from being completely bare!

I still cringe about the number of empty pages.  I must continue to put 
more content in... I believe it is killing the project at the moment.

>> The final hurdle is that even after you have edited the page and made 
>> it active it still isn't visible on the main Cocoon site until some 
>> arcane command line incantations are performed.
>
> I think having a staging docbase is not bad at all, it lets you revise 
> stuff before being published, not to mention the better performance of 
> the published site.

I just tried looking at the documentation for this [2] and noticed it 
has been updated.  It looks easier to do now!

Ok... you win!

Regards,
David Legg

[1] http://cocoon.apache.org/2.2/core-modules/core/2.2/1043_1_1.html
[2] http://cocoon.apache.org/1418_1_1.html

Mime
View raw message