Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: pass (nike.apache.org: domain of ap-cocoon-dev@m.gmane.org
 designates 80.91.229.2 as permitted sender)
To: dev@cocoon.apache.org
From: Luca Morandini <lmorandini@ieee.org>
Subject: Re: Spring Configurator Docs
Date: Thu, 12 Feb 2009 13:20:01 +0100
Lines: 46
Message-ID: <gn145i$2ms$1@ger.gmane.org>
References: 
 <F71A3F85F026644687388710AF44A200050014BF@srv-corp-exmb5.ciber.cbr.inc>
 <4993E3B3.507@apache.org>
 <7C655C04B6F59643A1EF66056C0E095E01F90B29@eusex01.sweden.ecsoft>
 <4993F048.7000701@apache.org> <49940222.7050901@searchevent.co.uk>
Reply-To: lmorandini@ieee.org
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
User-Agent: Thunderbird 2.0.0.18 (X11/20081119)
In-Reply-To: <49940222.7050901@searchevent.co.uk>
Sender: news <news@ger.gmane.org>

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