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
