cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luca Morandini <lmorand...@ieee.org>
Subject Re: Spring Configurator Docs
Date Thu, 12 Feb 2009 12:20:01 GMT
David Legg wrote:
> I have to agree that the current documentation system is a bit of a 
> nightmare.
> 
> As I see it there are too many hurdles that have to be passed through 
> before documents become visible to the general public.  I had a go at 
> updating a few pages using the Daisy system.  Editing an existing 
> document is easy enough but I never had the time to learn how to drive 
> the navigation sytem... and I suspect nobody else did either ;-)  This 
> is why moving between docs is so difficult.

Well, Daisy has a rather flexible way of grouping documents by using 
"collections" (one document may belong to more than one collection); I 
understand this is different from the strictly hierarchical way of, say, 
Confluence... but it is easier to maintain too.


> 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.


> 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.


> Bring back the wiki I say!

I beg to differ ;)

Regards,

--------------------
    Luca Morandini
www.lucamorandini.it
--------------------


Mime
View raw message