On Aug 26, 2006, at 12:53 PM, Craig L Russell wrote:
On Aug 22, 2006, at 10:43 AM, Marc Prud'hommeaux wrote:
Bryan-
Those points all sound good to me.
On Aug 22, 2006, at 9:34 AM, Bryan Noll wrote:
Thanks Craig for the link...
So... having caught up on that thread, seems like the following
are the key points:
1. People seem to like the easiness of wiki editing for the main
site. (If wiki content is specific to a particular release, it
would just be identified as such, much like this:
http://geronimo.apache.org/documentation.html)
The main issue with using wiki for the main site is that there are
no controls over who edits a wiki page (sort of a main idea of open
development).
If confluence is the wiki, you can grant read or write permissions to
groups and individuals on a per space and per page basis.
Geronimo is prototyping a Confluence-based website http://
cwiki.apache.org/GMOxSITE, in a space separate from it's "wiki", but
we haven't worked out all the details yet. Trying to work out
details like getting xml and html exports of the site into svn on
each edit, etc.
-David
So I'd feel very uncomfortable using a wiki as the primary landing
site for the project.
But I think a simple web site tied to a big wiki would be fine.
Geronimo changed from moinmoin to confluence, and confluence seems
to have a lot going for it. I'm not the expert, but I think we
should consider changing to cwiki.
2. It is a good thing to keep the official documentation for a
release with that release. This documentation should be
changing
less often than the stuff on the wiki, therefore the
'developery'
approach of having to to subversion check ins to the manual.xml
file is acceptable. Another example of the kind of content on
this site would be the javadoc, as that is specific to each
release, so http://issues.apache.org/jira/browse/OPENJPA-11
would
have to be re-worked.
Yes, version-specific javadoc and documentation should be built in
each release. The site then needs to be updated each release so
it's easy to find the doc.
3. It would be good if one could navigate to the full set of
release
specific documentation from 'The Site'. Rationale for this
provided by Craig here: *http://tinyurl.com/zbwz4*
4. Note: I'm throwing this one in - It would be good if their was
some continuity in terms of look and feel when navigating to
the
maven generated (via 'maven site') release specific stuff from
'The Site'. I assume the same skin can be applied to both 'The
Site' (current generated with ant via Anakia) and the
version-specific Maven generated sites.
Yes, I don't know how to do this, but I'm assuming that it's possible.
Craig
Does this sound agreeable? Anyone like to add anything to it...
or have any major issues with it?
Thanks...
Bryan
Craig L Russell wrote:
Hi Bryan,
The thread named "staging of site changes" dated 25-July is the
thread to which I referred. It has some expressed points of view
but no conclusion.
http://mail-archives.apache.org/mod_mbox/incubator-open-jpa-dev/
200607.mbox/thread
Craig
On Aug 22, 2006, at 8:43 AM, Bryan Noll wrote:
I'm having a hard time tracking down the thread regarding the
discussion about where the site and docs should be kept. Would
someone mind replying with a URL? I'd like to first go catch
up on that, and then maybe push for a decision from the
community so we can move ahead.
Thanks...
Marc Prud'hommeaux wrote:
Bryan-
- If the only thing stopping this stuff from getting to a
wiki is bandwidth of the current dev team, can someone
point me in the right direction so I can run with it?
I think that if Marc is willing to turn over his work in
progress to you then you can run with it. Just see if what
you intend is more or less permanent it belongs on the site,
and work-in-progress-needing-interaction belongs on the wiki.
My original idea was to generate the documentation from its
current location (at openjpa-project/src/doc/manual/
manual.xml), and generate the site and docs together using the
"mvn site" process (the output of which can be seen at http://
people.apache.org/~mprudhom/openjpa/site/ ). Other people
suggested that we keep the site and docs in a separate,
parallel Subversion directory, so I waited to do any further
work until we had come to some consensus on how the project
site and documentation should be handled.
Everything that I've done is currently checked into
Subversion, though. Any changes/additions to the docs can be
made to openjpa-project/src/doc/manual/manual.xml , which I
expect we will relocate to wherever we decide is the best
place for it.
On Aug 21, 2006, at 4:07 PM, Craig L Russell wrote:
On Aug 21, 2006, at 6:53 AM, Bryan Noll wrote:
Craig...
You seem to be one of the resident experts on infra-related
stuff. Can you comment on some of my questions in the mail?
Thanks...
Bryan Noll wrote:
So... I realize that OpenJPA is super-new to Apache, and
this is for sure the reason that the documentation is
currently located at what appears to be a non-permanent
place (http://people.apache.org/~mprudhom/openjpa/site/
openjpa-project/manual/index.html).
Yes, this is a non-permanent location. It's Marc's personal
space in Apache land.
- Is there a plan to migrate this stuff do a different
location? (either http://wiki.apache.org/incubator/openjpa/
or http://cwiki.apache.org/confluence/display/openjpa/Index)
I guess Marc knows best what the plans are.
- Is cwiki.apache.org preferred to wiki.apache.org?
Well, this is a personal preference, and it turns out that
openjpa actually has empty home pages on both sites (I
accidentally added some content to the cwiki which can be
moved to the wiki).
Personally, I'm not familiar with cwiki so I don't understand
its advantages or modus operandi. Maybe someone in the group
with more experience using these tools can comment. I didn't
find that adding a new page was trivial (and no, I didn't rtfm).
- There are certain resources that have bad links to non-
existent locations in the current documentation.
For instance: from here...
(http://people.apache.org/~mprudhom/openjpa/site/openjpa-
project/manual/jpa_tutorial.html#jpa_tutorial_files)
trying to get to here...
(http://people.apache.org/~mprudhom/openjpa/tutorial/
persistence/AnimalMaintenance.java)
Marc noted in a previous thread that, in this specific
case, the tutorial files simply had not been committed to
the apache repo yet. This is something I'm willing to
prepare a patch for.
I'd say that these should probably be moved to the "site"
area parallel to trunk.
There was an open question a while back on where the
tutorials belonged (either in site or in each release branch
plus trunk), and I don't know that we ever resolved this
question.
Not that the tutorial work is all that glorious, but it
seems like something that would be good to have available
for folks considering using OpenJPA who want to give the
project the 15 minute sniff test.
- My real motive in asking these questions is that I've run
across some documentation that I'd like to add to, and
wondered if/when it was going to make its way to a wiki so
people can contribute.
I think there's room for both site and wiki. I think there is
a discussion on this topic in the archives.
- If the only thing stopping this stuff from getting to a
wiki is bandwidth of the current dev team, can someone
point me in the right direction so I can run with it?
I think that if Marc is willing to turn over his work in
progress to you then you can run with it. Just see if what
you intend is more or less permanent it belongs on the site,
and work-in-progress-needing-interaction belongs on the wiki.
Craig
Thanks...
Bryan
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/
products/jdo
408 276-5638 mailto:[EMAIL PROTECTED]
P.S. A good JDO? O, Gasp!
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/
products/jdo
408 276-5638 mailto:[EMAIL PROTECTED]
P.S. A good JDO? O, Gasp!
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:[EMAIL PROTECTED]
P.S. A good JDO? O, Gasp!