openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bryan Noll <bwn...@gmail.com>
Subject Re: status of OpenJPA documentation
Date Tue, 22 Aug 2006 16:34:58 GMT
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!
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message