You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@openjpa.apache.org by Bryan Noll <bw...@gmail.com> on 2006/08/18 17:33:35 UTC
status of OpenJPA documentation
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).
- 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)
- Is cwiki.apache.org preferred to wiki.apache.org?
- 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. 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.
- 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?
Thanks...
Bryan
Re: status of OpenJPA documentation
Posted by Marc Prud'hommeaux <mp...@apache.org>.
The breaking up of the docs into separate files can be re-done fairly
easily (and perhaps in a cleaner way: we can have one file per
section, or something), so I don't think that is a showstopper.
As for formatting, is it the output formatting that looks wrong, or
something with the internal XML formatting? Being XML, the latter
should be easily correctable. The former might require a re-export,
though.
On Aug 18, 2006, at 12:29 PM, Abe White wrote:
>> - 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)
>>
>> - Is cwiki.apache.org preferred to wiki.apache.org?
>>
>> - There are certain resources that have bad links to non-existent
>> locations in the current documentation.
>
> I can't answer these questions, but I'll point out that the current
> documentation was automatically exported from our Kodo docs, and in
> the process the separation of files (we don't maintain one huge doc
> file for Kodo) and the formatting were lost. So at the very least,
> I believe we'll have to do a cleaner export to give us a better
> starting point before we start building on the docs. Unless, that
> is, we plan on automatically moving what's checked in now to yet
> another format, in which case the loss of formatting, etc is no
> longer an issue.
Re: status of OpenJPA documentation
Posted by Abe White <aw...@bea.com>.
> - 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)
>
> - Is cwiki.apache.org preferred to wiki.apache.org?
>
> - There are certain resources that have bad links to non-existent
> locations in the current documentation.
I can't answer these questions, but I'll point out that the current
documentation was automatically exported from our Kodo docs, and in
the process the separation of files (we don't maintain one huge doc
file for Kodo) and the formatting were lost. So at the very least, I
believe we'll have to do a cleaner export to give us a better
starting point before we start building on the docs. Unless, that
is, we plan on automatically moving what's checked in now to yet
another format, in which case the loss of formatting, etc is no
longer an issue.
_______________________________________________________________________
Notice: This email message, together with any attachments, may contain
information of BEA Systems, Inc., its subsidiaries and affiliated
entities, that may be confidential, proprietary, copyrighted and/or
legally privileged, and is intended solely for the use of the individual
or entity named in this message. If you are not the intended recipient,
and have received this message in error, please immediately return this
by email and then delete it.
Re: status of OpenJPA documentation
Posted by David Blevins <da...@visi.com>.
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:Craig.Russell@sun.com
>>>>>>> P.S. A good JDO? O, Gasp!
>>>>>>>
>>>>>>
>>>>>>
>>>>
>>>> Craig Russell
>>>> Architect, Sun Java Enterprise System http://java.sun.com/
>>>> products/jdo
>>>> 408 276-5638 mailto:Craig.Russell@sun.com
>>>> P.S. A good JDO? O, Gasp!
>>>>
>>
>
> Craig Russell
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 408 276-5638 mailto:Craig.Russell@sun.com
> P.S. A good JDO? O, Gasp!
>
Re: status of OpenJPA documentation
Posted by Craig L Russell <Cr...@Sun.COM>.
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). 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:Craig.Russell@sun.com
>>>>>> P.S. A good JDO? O, Gasp!
>>>>>>
>>>>>
>>>>>
>>>
>>> Craig Russell
>>> Architect, Sun Java Enterprise System http://java.sun.com/
>>> products/jdo
>>> 408 276-5638 mailto:Craig.Russell@sun.com
>>> P.S. A good JDO? O, Gasp!
>>>
>
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!
Re: status of OpenJPA documentation
Posted by Marc Prud'hommeaux <mp...@apache.org>.
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)
> 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.
> 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.
>
>
> 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:Craig.Russell@sun.com
>>>>> P.S. A good JDO? O, Gasp!
>>>>>
>>>>
>>>>
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/
>> jdo
>> 408 276-5638 mailto:Craig.Russell@sun.com
>> P.S. A good JDO? O, Gasp!
>>
Re: status of OpenJPA documentation
Posted by Bryan Noll <bw...@gmail.com>.
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)
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.
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.
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:Craig.Russell@sun.com
>>>> P.S. A good JDO? O, Gasp!
>>>>
>>>
>>>
>
> Craig Russell
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 408 276-5638 mailto:Craig.Russell@sun.com
> P.S. A good JDO? O, Gasp!
>
Re: status of OpenJPA documentation
Posted by Craig L Russell <Cr...@Sun.COM>.
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:Craig.Russell@sun.com
>>> P.S. A good JDO? O, Gasp!
>>>
>>
>>
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!
Re: status of OpenJPA documentation
Posted by Bryan Noll <bw...@gmail.com>.
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:Craig.Russell@sun.com
>> P.S. A good JDO? O, Gasp!
>>
>
>
RE: status of OpenJPA documentation
Posted by Patrick Linskey <pl...@bea.com>.
> 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.
My feeling is that the documentation (including tutorials and samples)
belongs with the product, and content about OpenJPA the project should
be separate from the product. I do not think that docs should move into
a wiki, although I do think that there are a bunch of advantages to
keeping the site content (i.e., the stuff that's not versioned along
with the product) all in a wiki, since I find wikis more accessible for
editing than HTML + SVN etc.
-Patrick
_______________________________________________________________________
Notice: This email message, together with any attachments, may contain
information of BEA Systems, Inc., its subsidiaries and affiliated
entities, that may be confidential, proprietary, copyrighted and/or
legally privileged, and is intended solely for the use of the individual
or entity named in this message. If you are not the intended recipient,
and have received this message in error, please immediately return this
by email and then delete it.
Re: status of OpenJPA documentation
Posted by Marc Prud'hommeaux <mp...@apache.org>.
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:Craig.Russell@sun.com
> P.S. A good JDO? O, Gasp!
>
Re: status of OpenJPA documentation
Posted by David Blevins <da...@visi.com>.
On Aug 21, 2006, at 4:07 PM, Craig L Russell wrote:
>
> 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.
Just to give you some idea, I updated the page you added:
http://cwiki.apache.org/confluence/display/openjpa/
DistributionStrategy
Then I exported it as a PDF.
http://people.apache.org/~dblevins/openjpa-20060821-19_41_51.pdf
It looks fairly good sans the JIRA content cause the table is too big
for the page.
> I didn't find that adding a new page was trivial (and no, I didn't
> rtfm).
As a note, you can create pages the MoinMoin way by simply
referencing [The Page] in your content using brackets as I just
did. Then when your content will have "The Page" as a hyperlink
that will allow you to create The Page when you click it. Unlike
MoinMoin, spaces are ok in page names.
I used to look at the Groovy confluence space quite a bit for
examples when I was first starting with Confluence:
http://docs.codehaus.org/display/GROOVY/Home
-David
Re: status of OpenJPA documentation
Posted by Craig L Russell <Cr...@Sun.COM>.
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:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!
Re: status of OpenJPA documentation
Posted by Bryan Noll <bw...@gmail.com>.
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).
>
>
> - 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)
>
> - Is cwiki.apache.org preferred to wiki.apache.org?
>
> - 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. 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.
>
> - 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?
>
> Thanks...
>
> Bryan
>