openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig L Russell <Craig.Russ...@Sun.COM>
Subject Re: status of OpenJPA documentation
Date Sat, 26 Aug 2006 19:53:50 GMT

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!


Mime
View raw message