openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marc Prud'hommeaux <mprud...@apache.org>
Subject Re: status of OpenJPA documentation
Date Tue, 22 Aug 2006 17:43:17 GMT
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!
>>


Mime
View raw message