geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Lin Sun" <linsun....@gmail.com>
Subject Re: Documentation of new 2.2 features in current wiki?
Date Thu, 07 Aug 2008 17:00:16 GMT
I agree that I don't really want to see a change of structure in
documentation unless someone can give a good reason to that.   I feel
I just learned on how to locate some of the good information in the
doc and I don't want to go through that learning again.

The prob of seeding 2.2 space with 2.1 content right now is that 2.1
content isn't finished yet.  If someone wants to make a change to 2.1
content, he'll have to change it in two places (both 2.1 and 2.2
docs).

Lin

On Thu, Aug 7, 2008 at 12:45 PM, Jason Warner <jaw981@gmail.com> wrote:
> If our goal is to have developers create documentation for new features when
> the feature is integrate, then I don't see why we shouldn't just create the
> 2.2 space now and seed it with 2.1 right away.  If no new features are added
> yet, then the old documentation applies just as much to 2.2 as it does to
> 2.1, and if new features are added and documented appropriately, then people
> can just use the appropriate documentation space for the appropriate
> version.  Basically, I'm saying I think we should seed the 2.2 documentation
> space now and update it as we go along.
>
> On Thu, Aug 7, 2008 at 11:43 AM, Jarek Gawor <jgawor@gmail.com> 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.
>>
>> 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
>> >>>>
>> >>>>
>> >>>
>> >
>> >
>
>
>
> --
> ~Jason Warner
>

Mime
View raw message