cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylv...@apache.org>
Subject Re: [VOTE] Consensus about documentation location
Date Mon, 13 Jun 2005 09:37:23 GMT
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


Mime
View raw message