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
|