cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leszek Gawron <lgaw...@mobilebox.pl>
Subject Re: [VOTE] Consensus about documentation location
Date Mon, 13 Jun 2005 14:12:04 GMT
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.
> 
>>
>>
>>> - 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
I do not propose to give access do editing formal documentation. Daisy 
has got a nice feature of several "sites" in one CMS. Let's make a 
scratchpad site that allows users to enter their experiences there.

> users a place to document things that they have learned which may not 
> have a good place in the formal documentation.  
What kind of documentation, faq, recipe, howto is not suitable for 
formal documentation? Every piece of someones writing can be:
- pointed out to have an existing docs entry
- processed and incorporated into formal docs somehow (I do not mean 1:1 
here)
- rejected because of quality issues

> 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.
I see an analogy but I keep my opinion:
- it will be much more appealing to users to post snippets to CMS scratchpad
- reviewing things and putting them live will happen using the same 
tools as for formal documentation (who will want to convert wiki markup 
-> html code?)
- Most of all: we will have one documenatation source instead of 2. Even 
if something is in scratchpad people may want to look for it and use it. 
   We could provide special search queries for formal documents only and 
one that would include awaiting documents.

-- 
Leszek Gawron                                      lgawron@mobilebox.pl
IT Manager                                         MobileBox sp. z o.o.
+48 (61) 855 06 67                              http://www.mobilebox.pl
mobile: +48 (501) 720 812                       fax: +48 (61) 853 29 65

Mime
View raw message