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
