Linden H van der (MI) wrote:
Guys,
I'm aware that I'm not officially a committer (yet), however, I think it
will be a good idea to get explicit consensus on where to locate the
docs and about a rough outline of the future actions.
This is the proposal:
- the current Daisy site at the zones [1] will be the "incubator" for
the new documentation. I.e. new content is to be entered there.
+1
- this documentation is targeted at Cocoon 2.2. This means that we try
to write version-independent documentation, but when there is a
difference between 2.1 and 2.2, the documentation will describe 2.2.
Same concerns as Ugo. We should IMO document 2.1 and use specially
labelled sections and pages for what's different in 2.2. We could also
uses Daisy branches, but I don't think it's a good idea to start a
multi-branch effort right now.
- the rules for the various roles have been defined already [2]. Note,
registered guests can leave comments.
+1
- this also implies that we stick with Daisy as CMS (and not venture on
the endless hunt for THE best system/toolset).
+1
- all current content in both wiki and "official docs" will be evaluated
and either deprecated or moved over into the Daisy site.
+1
- once the wiki is "processed" (i.e. all documentation is (re)moved), it
will only serve as a scratchpad, either for random thoughts/proposals or
for users that want to offer documentation but have no editor rights in
the Daisy site. I.e. the content of the wiki should be kept as small as
possible and deprecated information should be removed as soon as
possible.
Same concerns as Leszek: writing docs in the wiki would really make
non-editors feel like second-class citizen. Additionally to leaving
comments, we may allow registered users with no particular rights to
edit documents belonging to a "scratchpad" collection, distinct from the
main document collection. That will allow us to quickly move around good
contributions to the main area and also educate editor wannabees to the
CMS features.
- the current intention is to eventually move the content of the Daisy
site over to the "official documentation". This is no hard coded rule
and may be changed later.
A mod_rewrite rule pointing cocoon.apache.org/docs/ to the cocoon zone
(with an additional mod_cache?) will make publication damn easy :-)
Something important though is to keep a version of the docs in svn at
least for each release, so that we can easily find the docs for a
particular version, and also ship self-contained distros with their
docs. We therefore need a way to dump the content, either in published
form (e.g. with wget on the Daisy frontend) or in source form (by using
the http repository API [1])
Sylvain
[1] http://www.cocoondev.org/daisydocs-1_3/repository/interfaces/21.html
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
