David Jencks wrote:
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
Alright. When I created the new space I was attempting to get things
moving on the new documentation. I can see now that I didn't
accomplish that given the dilemma on how to merge in the 2.1 content.
Until we can resolve this I've done the following:
- Removed the reference to the new GMOxDOC22 space from the main
Geronimo wiki page. I did not yet delete this space in case we decide
we can still leverage it in some fashion (it took a little time to setup
the permissions, Geronimo banner, etc...). We can remove it at anytime
if necessary to create the final 22 documentation space.
- Created a "Geronimo 2.2 New Features" page to act as a parent for new
2.2 content under the GMOxDEV page (as suggested by Jarek)
- Added a link to the new temporary page next to the release documents
on the main documentation page. Yes, this means that there are 2 links
to the "Geronimo 2.2 New Features" page on the main page ... but I
thought it was important that this initial 2.2 doc be easy to find near
all of the other G version doc links. I think the users will have less
difficulty finding the doc and it will set a consistent expectation for
where they can find the full documentation when it is all merged together.
I hope that solves everybody's concerns and allows folks to start
documenting 2.2 features now while we figure out the best way to handle
the structure and mass population of the Geronimo 2.2 doc space.
Joe
Jarek
On Thu, Aug 7, 2008 at 11:02 AM, Joe Bohn <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]>
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
