Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: neutral (asf.osuosl.org: local policy)
Message-ID: <43451EA7.6090905@apache.org>
Date: Thu, 06 Oct 2005 14:55:03 +0200
From: Sylvain Wallez <sylvain@apache.org>
User-Agent: Mozilla Thunderbird 1.0.6 (Macintosh/20050716)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [Docs] Semi-automatic update process of the Cocoon documentation
References: <4345158D.7060608@gmail.com>
In-Reply-To: <4345158D.7060608@gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

hepabolu wrote:

> After talks to several people I feel we need a semi-automatic update 
> process of the Cocoon documentation to cocoon.apache.org.
>
> Several reasons:
> - frequent updates show users that there is concern about their 
> documentation wishes. We might even write documentation that answers 
> FAQs and point the users to that, rather than rewriting the 
> information on the mailing list.


This last sentence is IMO a very good idea from the community point of 
view for both users and developers.
- users will be educated to search first in the docs, as we will have 
good and up to date docs, which is a kind of revolution :-)
- developers will have go to the docs in search of information, which 
will make them care more about it. One of the current problems is that 
devs don't really need docs and thus don't care much about it (as we say 
in France: "far from the eyes is far from the heart").
- the documentation will be frequently updated based on user feeback and 
questions.

So this makes the documentation a part of the community conversations on 
the mailing-list. And this is very easy solution to help ensure it is 
kept up to date.

> - semi-automatic updates avoid the reinvention of the wheel for every 
> committer trying to update the website and avoid the errors that 
> created the current crippled site.
> - the current Daisy on the cocoon.zones contains the most recent 
> version of the documentation and provides an easier way of adding and 
> updating the documentation.
> - with the current update of Daisy, Daisy books have become available 
> and allow the documentation to be exported as a book in both HTML and 
> PDF.
>
> New process:
> - set up a small Cocoon branding website in the current xdocs section 
> with only a few pages that contain relative static content. Compare it 
> to the Springframework website.
> - These pages contain links to the actual reference documentation 
> which are available as Daisy book in both HTML (for browsing on the 
> website) and in PDF (for downloading and printing).
> - on cocoon.zones a Forrest configuration is setup with all the tweaks 
> necessary to get the job done.
> - a script is created that can do the Daisy books export, do the 
> Forrest conversion and the upload on the cocoon.apache.org site and 
> all the necessary steps in between.
> - the end result of the script is that the documentation is available 
> as a complete website on cocoon.apache.org AND for inclusion in the 
> next Cocoon release.
> - a secured "button" is available for committers to start this script. 
> Whether it is available as a password protected page, a ssh command or 
> whatever.
> - a notification can be sent to the dev-list when the site update 
> hasn't been done in X days.


This last point ensure we don't let the website become obsolete, without 
having to setup some completely automated publication which isn't good 
as we must have a human oversight on what is published on the official 
website.

> WDYT?


+1000 :-)

> It would be good to get the end result as described (but manual, 
> rather than semi-automatic for now) ASAP for inclusion in the upcoming 
> 2.1.8 release.


Another +1000. But we should not delay the release because of this, 
which probably means that the docs that will be shipped with 2.1.8 will 
not have a nice skin. But accurate information matters more than 
presentation.

Sylvain

-- 
Sylvain Wallez                        Anyware Technologies
http://people.apache.org/~sylvain     http://www.anyware-tech.com
Apache Software Foundation Member     Research & Technology Director