geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Jencks <david_jen...@yahoo.com>
Subject Re: Documentation of new 2.2 features in current wiki?
Date Thu, 07 Aug 2008 16:03:06 GMT

On Aug 7, 2008, at 8:43 AM, Jarek Gawor wrote:

> IMHO, the 2.2 space must be seeded from the 2.1 space. The question is
> just when to do it. That's why I suggested creating 2.2 content under
> some temporary space. Once we have the actual 2.2 space setup (from
> 2.1 content) then we can move these new pages into 2.2 space. It will
> be a lot easier to move just a few pages of the new content then merge
> lots of pages of 2.1 content into 2.2 space.

I agree.  IMNSHO the approach we used in 2.1 of not copying the entire  
previous documentation verbatim and modifying it but rather moving  
each page one at a time set us back at least one month and I don't  
think we've fully recovered.

I'd also like to request that in the 2.2 documentation there be _no_  
hand maintained tables of contents, indexes, etc.  My experience with  
them is that whatever the apparent benefit in terms of better ordering  
or nicer layout, the main effect they have is to conceal most of the  
newest documentation.  This would require some editing after the 2.1  
to 2.2 mass copy I'm hoping for.

thanks
david jencks

>
>
> Jarek
>
> On Thu, Aug 7, 2008 at 11:02 AM, Joe Bohn <joe.bohn@earthlink.net>  
> wrote:
>>
>> I agree in principle with creating a new location for 2.2 features  
>> to be
>> documented.  My only concern was that we are consistent so that the
>> documentation will be easy for users to find and easy to integrate  
>> when we
>> eventually do a mass merge from 2.1 to 2.2.
>>
>> So, I created a new space for 2.2 documentation to provide a  
>> consistent
>> structure and to capture the enthusiasm to document 2.2 changes.  I  
>> seeded
>> it with a top level structure that matches our 2.1 doc but no actual
>> content.  You can find it here:
>> http://cwiki.apache.org/GMOxDOC22/documentation.html
>>
>> I suggest that we create new content for 2.2 under this page for now:
>> http://cwiki.apache.org/GMOxDOC22/what-changed-in-22.html
>> .... I chose the current name to match what we had in 2.1.
>>
>> If a particular change has broad implications for documentation  
>> that is
>> already available in 2.1, we can copy current 2.1 content into 2.2  
>> and
>> modify it accordingly.
>>
>> As David pointed out earlier, we do not have the ability to  
>> automatically
>> merge the 2.1 content into the 2.2 content at a later time using this
>> approach.  Any merge will be a manual effort.  The only alternative  
>> I am
>> aware of would be to seed the new 2.2 space with the complete  
>> current 2.1
>> content.  However, that brings about some maintenance issues of  
>> keeping
>> things in sync and doesn't encourage 2.2 updates.  When we last  
>> discussed
>> this for 2.1 we decided to start with the empty space and so I took  
>> the same
>> approach for this release.
>>
>> I hope this provides something that will serve as a good place for  
>> the 2.2
>> content for now.  If we decide later that we should have started  
>> with a
>> complete copy of 2.1 we can always create a copy and merge the new  
>> 2.2
>> documents back into the 2.1 copy.  However, for now this at least  
>> provides a
>> place we can use and it is obvious to our users where they can find  
>> 2.2
>> documentation.
>>
>> Joe
>>
>>
>> Donald Woods wrote:
>>>
>>> Agree.  We could just create a "New Features in 2.2" page and  
>>> people can
>>> create child pages to it for their new features as they are  
>>> integrated into
>>> trunk....
>>>
>>>
>>> -Donald
>>>
>>>
>>> Jarek Gawor wrote:
>>>>
>>>> I think it would be nicer to create pages with 2.2 specific content
>>>> somewhere under http://cwiki.apache.org/GMOxDEV/index.html for now.
>>>> Once we have 2.2 documentation space setup we can move the pages
>>>> around. Or at least I don't think we should mix 2.2 content with  
>>>> 2.1
>>>> content.
>>>>
>>>> Jarek
>>>>
>>>> On Tue, Jul 29, 2008 at 1:52 PM, David Jencks <david_jencks@yahoo.com

>>>> >
>>>> wrote:
>>>>>
>>>>> I've been playing around with openid and jaspi and would like to  
>>>>> write
>>>>> up
>>>>> some documentation before I forget how it all works :-)
>>>>>
>>>>> I don't think we have enough people interested in documentation to
>>>>> pursue
>>>>> anything but the easiest-to-write path in documentation.  In  
>>>>> particular
>>>>> I
>>>>> think more than one active copy of the docs is asking for  
>>>>> disaster.
>>>>>
>>>>> I'd like to suggest that feature documentation should generally  
>>>>> start
>>>>> with a
>>>>> "starting with version xxx" comment.  So, I'd put the openid/jaspi
>>>>> documentation in the current (2.1) wiki with a "starting with 2.2"
>>>>> notice.
>>>>> Obviously there's the problem that the wiki has the 2.1 version  
>>>>> in its
>>>>> name. I don't know if a wiki can have its name changed but don't  
>>>>> regard
>>>>> this
>>>>> as critical.
>>>>>
>>>>> I'm going to start doing this pending comments and better  
>>>>> ideas.  At the
>>>>> rate I write I don't think I'll be causing significant damage  
>>>>> before we
>>>>> have
>>>>> time for a full discussion :-)
>>>>>
>>>>> thanks
>>>>> david jencks
>>>>>
>>>>>
>>>>
>>
>>


Mime
View raw message