incubator-yoko-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Geir Magnusson Jr." <g...@pobox.com>
Subject Re: docs: core orb config parameters
Date Tue, 02 Jan 2007 23:05:36 GMT

On Jan 2, 2007, at 3:22 PM, Lars Kühne wrote:

> Alan D. Cabrera wrote:
>>
>> On Jan 1, 2007, at 10:59 AM, Lars Kühne wrote:
>>
>>> OK, I've started the OrbConfiguration page.
>>>
>>> However, I think that ultimately such information depends on the  
>>> ORB version, so it would be better to have it in svn, along with  
>>> the code it documents.
>>>
>>> As a user, I would expect that this info is be part of the  
>>> product download, and it's not clear to me how to do this. The  
>>> technical problems of creating a snapshot from Maven might be  
>>> solvable, but how do we handle the IP issues when non-committers  
>>> contribute to the wiki?
>>>
>>> Anyway, I've started collecting the information in the wiki for  
>>> now, as you suggested.
>>
>> Storing documentation in a wiki is a standard ASF practice.
>
> I'm not at all opposed to that, quite the contrary. It's great to  
> have docs on the wiki, and I would love to see more, especially  
> developer documentation, technical overviews, and such.
>
> It's just that I'd like to see some of the docs inside the tarball  
> as well. As a user, this means that when I download and use the  
> product I can be sure that I'll always have access to the exact  
> documentation. Nobody will ever delete it while I still use the  
> product, which may happen if the docs are only available in a wiki  
> (or any other website for that matter).

Absolutely - I think it's insane when projects don't do this.

>
> Take the Apache Derby download for example. That zip includes a  
> reference guide which (among other things) lists the SQLStates.  
> Very version specific and will change from release to release, so I  
> like it that no one can delete that info from under my feed in the  
> future.
>
> Maybe I'm paranoid ;-)
>
>>   The whole point of having the wiki is to let the community to  
>> contribute to the documentation.  IIUC, committers are not  
>> necessarily the IP guardians.  Committers are people who can  
>> competently integrate code and patches into the code base.
>
> My understanding was that "we" (PPMC/commiters) should ensure that  
> we don't include stuff in our release tarball that we legally  
> cannot distribute. See my response to Geir for details.
>
>> Geronimo does a great job at handling versions, http:// 
>> cwiki.apache.org/geronimo/.
>
> As far as I can see you have a confluence space for each version of  
> Geronimo. We only have one "space" (or whatever it's called in  
> MoinMoin) available for Yoko, so I'm not sure how we could mimic  
> what you did for Geronimo.

If you were going to do this, you'd do it in confluence too.

Or you can just harvest good material from time to time from a wiki  
and add to a in-svn documentation tree.  it also encourages people to  
send patches to the project for that doco tree, helping you identify  
new committers.

geir


>
> Regards,
> Lars
>


Mime
View raw message