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:35:27 GMT

On Jun 13, 2005, at 8:46 AM, Ralph Goers wrote:

> Sylvain Wallez wrote:
>
>
>>
>> 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.
>>
>
> I agree with this also.
>

I know how slowly I can work sometimes, so 2.2 is a good target for  
me. ;-)  I think what we want is to have current documentation. When  
2.2 is released we want to be ready. We don't want to go back and  
update documentation that we have just finished, especially if we  
could have incorporated it as we went along. Likewise I don't see us  
ignoring 2.1, since no one in there right mind would ever use the  
latest relaease :-O. We can't document anything that doesn't exist  
yet, but we do have to work with the latest versions in order to stay  
current. If developers are working on 2.2, the documentarians need to  
be as well. Right now I think each of the "documentarians" has a pet  
project. What I hope is that in the future (or even now) that if  
commiters need new functionality documented they will feel free to  
ask us to do it. That is the role we play.


>
>>
>>
>>
>>> - 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.
>>
>
> Here I have to disagree with you.  I don't think that all the  
> content that is on the Wiki should necessarily find its way to  
> the :"formal" documentation.  I think the wiki serves that purpose  
> well.  It allows users a place to document things that they have  
> learned which may not have a good place in the formal  
> documentation.  So, just because users can't directly update the  
> formal documentation I don't think they will feel like second class  
> citizens. I think they'd be quite surprised if they could update  
> the formal documentation.  And actually, I think they would be  
> quite pleased and honored if whatever they wrote was moved from the  
> wiki into the formal docmentation by an editor.
>
> I really don't see this as much different than how things are with  
> the code.  Users can write patches and submit them to bugzilla or  
> they can post code snippets on the wiki, but they cannot update svn.

One of the things we'd like to get out of this is more user  
participation. What I'd like to see is the Daisy site replace the  
wiki for documentation purposes. I'd like guest to be able to browse  
unfinished and incomplete documentation. I'd like anyone to be able  
to write documentation and submit it for publication. The wiki still  
has a place, but I've never seen as appropriate way to document things.



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