cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Ezkovich <g...@hard-bop.com>
Subject Re: [VOTE] Consensus about documentation location
Date Mon, 13 Jun 2005 14:13:42 GMT

On Jun 13, 2005, at 3:27 AM, Ugo Cei wrote:

> Il giorno 13/giu/05, alle 09:53, Leszek Gawron ha scritto:
>
>
>> Linden H van der (MI) wrote:
>>
>>> - 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.
>>>
>
> Why 2.2? I'm afraid (but would love to be proved wrong) that it's  
> going to be a while before we have 2.2 out the door. Most users are  
> targeting 2.1 and it will be the latest officially released version  
> for a long time.
>
> Moreover, many things in 2.2 are not finalized yet, so we'd be  
> documenting a moving target.

True. Documenting 2.1 means that by the time I have completed my work  
it will be obsolete. Most if the information will be back compatible,  
but where there are differences they need to be noted. Documentation  
developement usually goes along with code development. One of the  
problems with documenting Cocoon is the the activity of the  
developers. Once we have some basics in place I can concentrate on  
keeping the docs current.

>
>
>>> - this also implies that we stick with Daisy as CMS (and not  
>>> venture on
>>> the endless hunt for THE best system/toolset).
>>>
>
> +1

I look at this as an experiment. If it works great if it doesn't we  
need to find something else. Right now daisy seems to have some  
limitations. We can work around them for now.

>
>
>>> - 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.
>>>
>> It would be quite awkward if we have a documentation site but  
>> direct users to write their howtos and recipes on empty wiki. It  
>> looks like you'd be saying to a common: You're not worth using our  
>> CMS. Write some content in our trash-all-there wiki and we will  
>> kindly pick it up from there. OR NOT.

One of the current limitations of Daisy is that we have only 3 roles.  
We need a fourth.  Publishers, who make a document official and  
publish it to the main documentation site. Editors, who can view,  
edit and comment on the work of others. Writers, who can work only on  
their own documents. Guests who can view any document in in any  
state. Even unfinished and unacceptable documents have valuable  
information.

>>
>> My thought: make user registration at CMS as easy as possible.  
>> Grant edit rights in Daisy for some cocoon-documentation-firing- 
>> ground site. Pick documents from there and put it into main  
>> documentation with ease when the document is mature enough. On  
>> wiki users also have to register before editing and that did not  
>> make problems.

Registration is a must.

>>
>
> +1
>
>
>>> - 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.
>>>
>> What for really? We will have whole content there (with metadata  
>> and comments). Why not make it default cocoon.apache.org? Every  
>> new cocoon release would get a static snapshot of online site.

Glen Ezkovich
HardBop Consulting
glen at hard-bop.com



A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to  
worry about answers."
- Thomas Pynchon Gravity's Rainbow


Mime
View raw message