Re: Documentation of new 2.2 features in current wiki?
To get things moving I went ahead and did an export of the current Geronimo 2.1 space (GMOxDOC21) and restored it as Geronimo 2.2 (GMOxDOC22). I only changed the space name and the initial title so there are tons of references to Geronimo 2.1 in this new space still. Here's a link to the new space: http://cwiki.apache.org/GMOxDOC22/documentation.html As you can see it looks a lot like the 2.1 space still since it has not yet been updated with any 2.2 specifics (beyond a few title changes). Everyone, Now that we have 2 spaces we will need to mirror appropriate updates in the 2.1 space into the 2.2 space. Please help us keep the doc consistent where appropriate. Also, feel free to update the new space with specifics for Geronimo 2.2 now that we have it. Rebekah, I think this should get you moving on making the proposed updates. Please update/remove/etc... the references to Geronimo 2.1 as necessary to reflect that this is for Geronimo 2.2. Thanks, Joe wei zhang wrote: Well, only the Export/Restore actions require administrator authority. Others like move and copy pages can be done by author, and I have tried those actions. On 8/19/08, *Joe Bohn* [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] wrote: Hmmm ... it seems that we might have a problem then. If admin authority is required to export/restore then it is also most likely the case that admin is required to move pages and such for the proposed new structure. It might not be possible for Rebekah to make these changes. I'm also wondering if we are really at the point where it makes sense to copy the 2.1 doc to 2.2 and start incurring the duplicate maintenance costs. There are not yet any 2.2 pages created under the parent page that we made for that purpose. Is now really the time to export/restore? Joe PS. I also attempted to do a quick export/restore with a very simple space prior to leaving for vacation. I had some problems too ... I can't recall what they were at the moment ... I'll have to give it another shot ... but there might be more than just an authority issue with this process. wei zhang wrote: Hi I tried the Export/Restore option David Belvins suggested, but couldn't make any progress because only the administrator can perfrom such actions. Can someone with administrator authority help? Thanks. Rebekah Zhang On 8/19/08, *David Jencks* [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] mailto:[EMAIL PROTECTED] mailto:[EMAIL PROTECTED] wrote: On Aug 17, 2008, at 11:28 PM, Jack Cai wrote: Is someone working on copying 2.1 space to 2.2? :-) If we don't have a solution for the copy approach, maybe we just let Rebekah and her colleagues go ahead to manually copy reorganize... David Blevins posted fairly complete instructions for the various options on aug 1 in this thread. Is there some problem with doing export/restore? thanks david jencks -Jack
Re: Documentation of new 2.2 features in current wiki?
I am concerned at making changes in two places and we should eliminate that if possible. Should we only copy the documents that are complete? Is the check mark next to the document link a good indication of completeness? Lin On Wed, Aug 20, 2008 at 4:39 PM, Joe Bohn [EMAIL PROTECTED] wrote: Everyone, Now that we have 2 spaces we will need to mirror appropriate updates in the 2.1 space into the 2.2 space. Please help us keep the doc consistent where appropriate. Also, feel free to update the new space with specifics for Geronimo 2.2 now that we have it. Thanks, Joe
Re: Documentation of new 2.2 features in current wiki?
Lin Sun wrote: I am concerned at making changes in two places and we should eliminate that if possible. Should we only copy the documents that are complete? Is the check mark next to the document link a good indication of completeness? I agree with the concern (in fact I raised it myself yesterday) ... but it seems that the time is right to start the 2.2 doc. We have people willing to jump in and help out with a new structure (like Rebekah and Jack) that were currently stuck and people were also interested in documenting 2.2 functions. It was agreed that seeding the 2.2 doc from the 2.1 space was the right approach. Unfortunately, the export/restore is an all or nothing proposition. You either copy the entire space or manually copy each individual page. I have no idea if the checkmarks are accurate ... but I suspect they are not. As far as maintaining the 2 docs, I think we all should take the following approach: - Treat the 2.2 documentation as the primary documentation. In other words, update this first if there are changes to be made. - Mirror updates from the 2.2 doc back to the 2.1 doc. That way, if there is any discrepancy we will know that the 2.2 doc is more correct and the things just might not have been mirrored back to 2.1 (or perhaps changed in 2.2). Joe Lin On Wed, Aug 20, 2008 at 4:39 PM, Joe Bohn [EMAIL PROTECTED] wrote: Everyone, Now that we have 2 spaces we will need to mirror appropriate updates in the 2.1 space into the 2.2 space. Please help us keep the doc consistent where appropriate. Also, feel free to update the new space with specifics for Geronimo 2.2 now that we have it. Thanks, Joe
Re: Documentation of new 2.2 features in current wiki?
I wish there is a way to tag a document page and say that it applies to whatever release(s), then we can generate user docs for a release based on documents that are tagged for that release. It seems reasonable for certain document pages to stay the same between multiple releases. Lin On Wed, Aug 20, 2008 at 5:27 PM, Joe Bohn [EMAIL PROTECTED] wrote: Lin Sun wrote: I am concerned at making changes in two places and we should eliminate that if possible. Should we only copy the documents that are complete? Is the check mark next to the document link a good indication of completeness? I agree with the concern (in fact I raised it myself yesterday) ... but it seems that the time is right to start the 2.2 doc. We have people willing to jump in and help out with a new structure (like Rebekah and Jack) that were currently stuck and people were also interested in documenting 2.2 functions. It was agreed that seeding the 2.2 doc from the 2.1 space was the right approach. Unfortunately, the export/restore is an all or nothing proposition. You either copy the entire space or manually copy each individual page. I have no idea if the checkmarks are accurate ... but I suspect they are not. As far as maintaining the 2 docs, I think we all should take the following approach: - Treat the 2.2 documentation as the primary documentation. In other words, update this first if there are changes to be made. - Mirror updates from the 2.2 doc back to the 2.1 doc. That way, if there is any discrepancy we will know that the 2.2 doc is more correct and the things just might not have been mirrored back to 2.1 (or perhaps changed in 2.2). Joe Lin On Wed, Aug 20, 2008 at 4:39 PM, Joe Bohn [EMAIL PROTECTED] wrote: Everyone, Now that we have 2 spaces we will need to mirror appropriate updates in the 2.1 space into the 2.2 space. Please help us keep the doc consistent where appropriate. Also, feel free to update the new space with specifics for Geronimo 2.2 now that we have it. Thanks, Joe
Re: Documentation of new 2.2 features in current wiki?
Joe, thanks for doing this. The maintenance of multiple spaces is worth enabling the community to start working on the 2.2 docs. -Donald Joe Bohn wrote: To get things moving I went ahead and did an export of the current Geronimo 2.1 space (GMOxDOC21) and restored it as Geronimo 2.2 (GMOxDOC22). I only changed the space name and the initial title so there are tons of references to Geronimo 2.1 in this new space still. Here's a link to the new space: http://cwiki.apache.org/GMOxDOC22/documentation.html As you can see it looks a lot like the 2.1 space still since it has not yet been updated with any 2.2 specifics (beyond a few title changes). Everyone, Now that we have 2 spaces we will need to mirror appropriate updates in the 2.1 space into the 2.2 space. Please help us keep the doc consistent where appropriate. Also, feel free to update the new space with specifics for Geronimo 2.2 now that we have it. Rebekah, I think this should get you moving on making the proposed updates. Please update/remove/etc... the references to Geronimo 2.1 as necessary to reflect that this is for Geronimo 2.2. Thanks, Joe wei zhang wrote: Well, only the Export/Restore actions require administrator authority. Others like move and copy pages can be done by author, and I have tried those actions. On 8/19/08, *Joe Bohn* [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] wrote: Hmmm ... it seems that we might have a problem then. If admin authority is required to export/restore then it is also most likely the case that admin is required to move pages and such for the proposed new structure. It might not be possible for Rebekah to make these changes. I'm also wondering if we are really at the point where it makes sense to copy the 2.1 doc to 2.2 and start incurring the duplicate maintenance costs. There are not yet any 2.2 pages created under the parent page that we made for that purpose. Is now really the time to export/restore? Joe PS. I also attempted to do a quick export/restore with a very simple space prior to leaving for vacation. I had some problems too ... I can't recall what they were at the moment ... I'll have to give it another shot ... but there might be more than just an authority issue with this process. wei zhang wrote: Hi I tried the Export/Restore option David Belvins suggested, but couldn't make any progress because only the administrator can perfrom such actions. Can someone with administrator authority help? Thanks. Rebekah Zhang On 8/19/08, *David Jencks* [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] mailto:[EMAIL PROTECTED] mailto:[EMAIL PROTECTED] wrote: On Aug 17, 2008, at 11:28 PM, Jack Cai wrote: Is someone working on copying 2.1 space to 2.2? :-) If we don't have a solution for the copy approach, maybe we just let Rebekah and her colleagues go ahead to manually copy reorganize... David Blevins posted fairly complete instructions for the various options on aug 1 in this thread. Is there some problem with doing export/restore? thanks david jencks -Jack smime.p7s Description: S/MIME Cryptographic Signature
Re: Documentation of new 2.2 features in current wiki?
Hmmm ... it seems that we might have a problem then. If admin authority is required to export/restore then it is also most likely the case that admin is required to move pages and such for the proposed new structure. It might not be possible for Rebekah to make these changes. I'm also wondering if we are really at the point where it makes sense to copy the 2.1 doc to 2.2 and start incurring the duplicate maintenance costs. There are not yet any 2.2 pages created under the parent page that we made for that purpose. Is now really the time to export/restore? Joe PS. I also attempted to do a quick export/restore with a very simple space prior to leaving for vacation. I had some problems too ... I can't recall what they were at the moment ... I'll have to give it another shot ... but there might be more than just an authority issue with this process. wei zhang wrote: Hi I tried the Export/Restore option David Belvins suggested, but couldn't make any progress because only the administrator can perfrom such actions. Can someone with administrator authority help? Thanks. Rebekah Zhang On 8/19/08, *David Jencks* [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] wrote: On Aug 17, 2008, at 11:28 PM, Jack Cai wrote: Is someone working on copying 2.1 space to 2.2? :-) If we don't have a solution for the copy approach, maybe we just let Rebekah and her colleagues go ahead to manually copy reorganize... David Blevins posted fairly complete instructions for the various options on aug 1 in this thread. Is there some problem with doing export/restore? thanks david jencks -Jack
Re: Documentation of new 2.2 features in current wiki?
Well, only the Export/Restore actions require administrator authority. Others like move and copy pages can be done by author, and I have tried those actions. On 8/19/08, Joe Bohn [EMAIL PROTECTED] wrote: Hmmm ... it seems that we might have a problem then. If admin authority is required to export/restore then it is also most likely the case that admin is required to move pages and such for the proposed new structure. It might not be possible for Rebekah to make these changes. I'm also wondering if we are really at the point where it makes sense to copy the 2.1 doc to 2.2 and start incurring the duplicate maintenance costs. There are not yet any 2.2 pages created under the parent page that we made for that purpose. Is now really the time to export/restore? Joe PS. I also attempted to do a quick export/restore with a very simple space prior to leaving for vacation. I had some problems too ... I can't recall what they were at the moment ... I'll have to give it another shot ... but there might be more than just an authority issue with this process. wei zhang wrote: Hi I tried the Export/Restore option David Belvins suggested, but couldn't make any progress because only the administrator can perfrom such actions. Can someone with administrator authority help? Thanks. Rebekah Zhang On 8/19/08, *David Jencks* [EMAIL PROTECTED] mailto: [EMAIL PROTECTED] wrote: On Aug 17, 2008, at 11:28 PM, Jack Cai wrote: Is someone working on copying 2.1 space to 2.2? :-) If we don't have a solution for the copy approach, maybe we just let Rebekah and her colleagues go ahead to manually copy reorganize... David Blevins posted fairly complete instructions for the various options on aug 1 in this thread. Is there some problem with doing export/restore? thanks david jencks -Jack
Re: Documentation of new 2.2 features in current wiki?
Is someone working on copying 2.1 space to 2.2? :-) If we don't have a solution for the copy approach, maybe we just let Rebekah and her colleagues go ahead to manually copy reorganize... -Jack
Re: Documentation of new 2.2 features in current wiki?
On Aug 17, 2008, at 11:28 PM, Jack Cai wrote: Is someone working on copying 2.1 space to 2.2? :-) If we don't have a solution for the copy approach, maybe we just let Rebekah and her colleagues go ahead to manually copy reorganize... David Blevins posted fairly complete instructions for the various options on aug 1 in this thread. Is there some problem with doing export/restore? thanks david jencks -Jack
Re: Documentation of new 2.2 features in current wiki?
Hi I tried the Export/Restore option David Belvins suggested, but couldn't make any progress because only the administrator can perfrom such actions. Can someone with administrator authority help? Thanks. Rebekah Zhang On 8/19/08, David Jencks [EMAIL PROTECTED] wrote: On Aug 17, 2008, at 11:28 PM, Jack Cai wrote: Is someone working on copying 2.1 space to 2.2? :-) If we don't have a solution for the copy approach, maybe we just let Rebekah and her colleagues go ahead to manually copy reorganize... David Blevins posted fairly complete instructions for the various options on aug 1 in this thread. Is there some problem with doing export/restore? thanks david jencks -Jack
Re: Documentation of new 2.2 features in current wiki?
Been watching this conversation with interest... since the discussion has lagged, thought I'd throw a bit more fuel on the fire to completely burn down the topic. So here's what I see... 1) Developers need a 'low friction' place to document new content The process needs to be dirt simple... go to wiki page 'foo', add page, add documentation to the page, done. Predictable, same process everytime, no need for the developers to figure out where it needs to go in the final doc tree (what is the final doc tree anyway), no need for the developer to necessarily even understand the project's overall documentation structure. Developers need a place to just catch the essential facts, and move on. Uncertainty of the developer about where to write the doc, or how to format it, or anything will increase the probability the developer will just conclude writing anything is just not worth the effort. Lower barriers to entry... make easy for developers to capture their ideas, leave the organization to someone who likes to do that sort of work. I've heard a couple of ideas here... Jarek suggested creating new content under a temp space. Joe said 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 . David's 'clearly tagging new doc with a version statement' is a variation of the above. Sounds reasonable to me, and unless I misread any of the replies, I think this meets the developer's requirements and I don't think it is on conflict with Rebekah's proposal. 2) On going maintenance of the doc David's primary concern (which I share) is that what ever process we adopt for G documentation should lend itself to being maintained. If all we have are developers maintaining documentation, then our doc structure will 'trend to' being flat and unorganized because that requires the least maintenance. If all we have is developers maintaining the documentation, I also agree with David's conclusion that we should maintain a single documentation tree and tag new doc with a clear version statement. However. if I've not misread any emails, I think Rebekah is volunteering (with help from her colleagues) to maintain the structure of our documentation, and create a new doc tree for each release of G (or a least when it make sense to create a new doc tree. The idea that she is volunteering to maintain the structure for the development team is the essential point... not the specific decisions about the exact nature of the structure of the final documentation). 3) Documentation structure... If Rebekah can maintain the doc structure she has proposed going forward while also enabling the developers to easily create new doc for new features, then I am a strong +1 to following her lead. Conclusion: We have someone showing up in the community to start what is essentially an Apache Geronimo documentation project tuned to the needs of the development community but offloading a lot of the 'chore' of maintaining the doc structure from the development community. What's not to like here? .. let's make sure that the basic needs of the development community are met then let's get out of her way and let her contribute. BTW, +1 for the 'single document' (infocenter? what's that?) approach. I strongly dislike the 'users' vs 'developers' bifurcation; the two are indistinguishable in the Geronimo community. Bill Joe Bohn wrote: Hi Rebekah, I just posted a note about a new space that I created for the 2.2 documentation. The new space was really created just to get things moving for 2.2. It was not a statement of what the final structure should be ... so please feel free to continue to explore this area and receive comments. I personally haven't had a chance to consider the alternatives you presented below. However, my inclination is to keep the current structure as is unless there are obvious problems with the organization and there are resources willing to invest the time and effort to change things. Can you provide some more information on what is driving the changes that you are proposing? Thanks, Joe wei zhang wrote: Hi there, This is Rebekah and I've been reading through the documentation with my colleagues for a while. I think we can keep the current version of the documentation and create another space for v2.2, because there will be users who may want to track the previous information. Regarding the organization of information, we have worked out new documentation structures based on the 2.1 info using two different appraches: one is pretty much book based, keeping some of the current lookfeel; the other is info center based. If we are going to create a new space for v2.2, we can take either approach. As long as the structure is ready, people can take topics they are interested in and write up the content. If you have any ideas or comments on the proposed structures,
Re: Documentation of new 2.2 features in current wiki?
On Aug 11, 2008, at 1:25 PM, bill stoddard wrote: Been watching this conversation with interest... since the discussion has lagged, thought I'd throw a bit more fuel on the fire to completely burn down the topic. So here's what I see... 1) Developers need a 'low friction' place to document new content The process needs to be dirt simple... go to wiki page 'foo', add page, add documentation to the page, done. Predictable, same process everytime, no need for the developers to figure out where it needs to go in the final doc tree (what is the final doc tree anyway), no need for the developer to necessarily even understand the project's overall documentation structure. Developers need a place to just catch the essential facts, and move on. Uncertainty of the developer about where to write the doc, or how to format it, or anything will increase the probability the developer will just conclude writing anything is just not worth the effort. Lower barriers to entry... make easy for developers to capture their ideas, leave the organization to someone who likes to do that sort of work. I've heard a couple of ideas here... Jarek suggested creating new content under a temp space. Joe said 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 . David's 'clearly tagging new doc with a version statement' is a variation of the above. Sounds reasonable to me, and unless I misread any of the replies, I think this meets the developer's requirements and I don't think it is on conflict with Rebekah's proposal. 2) On going maintenance of the doc David's primary concern (which I share) is that what ever process we adopt for G documentation should lend itself to being maintained. If all we have are developers maintaining documentation, then our doc structure will 'trend to' being flat and unorganized because that requires the least maintenance. If all we have is developers maintaining the documentation, I also agree with David's conclusion that we should maintain a single documentation tree and tag new doc with a clear version statement. However. if I've not misread any emails, I think Rebekah is volunteering (with help from her colleagues) to maintain the structure of our documentation, and create a new doc tree for each release of G (or a least when it make sense to create a new doc tree. The idea that she is volunteering to maintain the structure for the development team is the essential point... not the specific decisions about the exact nature of the structure of the final documentation). 3) Documentation structure... If Rebekah can maintain the doc structure she has proposed going forward while also enabling the developers to easily create new doc for new features, then I am a strong +1 to following her lead. Conclusion: We have someone showing up in the community to start what is essentially an Apache Geronimo documentation project tuned to the needs of the development community but offloading a lot of the 'chore' of maintaining the doc structure from the development community. What's not to like here? .. let's make sure that the basic needs of the development community are met then let's get out of her way and let her contribute. BTW, +1 for the 'single document' (infocenter? what's that?) approach. I strongly dislike the 'users' vs 'developers' bifurcation; the two are indistinguishable in the Geronimo community. I agree. I'm in favor of anyone who wants to reorganize the documentation doing so. I hope anyone who undertakes this will keep in mind that they might not be here forever and will consider ease of maintenance by developers and other documentation non-experts as a criterion in their decisions. thanks david jencks Bill Joe Bohn wrote: Hi Rebekah, I just posted a note about a new space that I created for the 2.2 documentation. The new space was really created just to get things moving for 2.2. It was not a statement of what the final structure should be ... so please feel free to continue to explore this area and receive comments. I personally haven't had a chance to consider the alternatives you presented below. However, my inclination is to keep the current structure as is unless there are obvious problems with the organization and there are resources willing to invest the time and effort to change things. Can you provide some more information on what is driving the changes that you are proposing? Thanks, Joe wei zhang wrote: Hi there, This is Rebekah and I've been reading through the documentation with my colleagues for a while. I think we can keep the current version of the documentation and create another space for v2.2, because there will be users who may want to track the previous information. Regarding the organization of information, we have worked out
Re: Documentation of new 2.2 features in current wiki?
Didn't we agree to seed the 2.2 space from 2.1 space first and then reorganize it? Jarek On Mon, Aug 11, 2008 at 10:29 PM, wei zhang [EMAIL PROTECTED] wrote: So I'll start together with my colleagues to seed the 2.2 space http://cwiki.apache.org/confluence/display/GMOxDOC22/Documentation with the new information center based structure. I hope to get more comments from the community that will help improve the documentation. Thanks.
Re: Documentation of new 2.2 features in current wiki?
My previous email was intended to be sent out earlier...not sure what was wrong with my gmail... The question now is not about 2.1--2.2--Reorganize or 2.1--Reorganize--2.2. I'm fine with both approaches, as long as I can contribute to the community with somethings that helps. Yes, Bill, I am volunteering to maintain the documentation. My original idea was to work out the structure and see how the community would like it, and then populate the 2.2 doc with the content under the new structure, but the discussion went on to the maintenance issue. Documentation is a big part of the development effort. Having developers themselves develop and maintain both the functions and the documentation is really a headache, which is why many folks tend to keep the status quo. With the documentation coordination work somewhat separated from technical development effort, developers will be able to focus on the fancy features, contribute information about what tasks the users can complete with the features, and leave the rest to the documentation coordinator. I agree with David that ease of maintenance is important. If we start from a solid base, the future maintenance work won't be too much of a problem. And this documentation project might attract more interested people as time goes by... Per previous discussions, we might have difficulty importing the whole 2.1 space to 2.2. If anyone knows how to copy the entire 2.1 space to 2.2, I will be able to work with my colleagues to reorganize the content then. If copying the space is sheer manual effort, I might want to start from the new structure and flesh it with the existing information. Thanks. Rebekah On 8/12/08, Jarek Gawor [EMAIL PROTECTED] wrote: Didn't we agree to seed the 2.2 space from 2.1 space first and then reorganize it? Jarek On Mon, Aug 11, 2008 at 10:29 PM, wei zhang [EMAIL PROTECTED] wrote: So I'll start together with my colleagues to seed the 2.2 space http://cwiki.apache.org/confluence/display/GMOxDOC22/Documentation with the new information center based structure. I hope to get more comments from the community that will help improve the documentation. Thanks.
Re: Documentation of new 2.2 features in current wiki?
Thanks Joe for all the work here! After going through the new structure proposed by Rebekah, I would say it is a derived version from 2.1, instead of a whole new structure. So I don't think somebody familar with the current 2.1 structure would need much time to get familiar with the new structure. And for new users, the new structure seems earier to start with. It is more natural and is better organized from user's point of view, instead of technology-oriented. Users turn to the documentation when they met some problems and cannot figure it out by exploring the software alone(so ideal software should be self-evident with their UI and do not need any doc :-)), so many product documentation nowadays are usally scenario or task oriented. I guess Rebekah can do a better job in explaining this to us since she has been working on product documentation for several years. We do have some resource available to do the migration from 2.1 to 2.2 doc manually. So if we could agree that we can have a better doc structure, we can put the new structure on the new wiki space and have more discussion on the structure itself. We definitely need your opinions to make it better... Currently Rebekah has made 2 proposals, 1 follows 2.1 which divides the doc into user's guide and developer's guide, the other integrates them together. Personally I prefer the latter because it simplifies user's view. I would say most, if not all, geronimo users are also developers. So it will be easier for user to locate information based on their tasks instead of asking them to decide whether he/she is a user or a developer beforehands (which typically ends up browsing both guides). Open for your comments.
Re: Documentation of new 2.2 features in current wiki?
Thank you for the additional information Rebekah. I didn't intend to imply that change was bad ... I just wanted to better understand the what was driving the change. Change just for the sake of change can be useless and produce less than desirable results. I now understand the problems that you are trying to solve and agree that some changes are necessary. I agree with Jacek that I prefer the merged (infocenter) style approach. Overall, I like the organization that you have proposed. I have just 2 initial alternative ideas to propose on the structure: 1) I would move the the content of section 3.2 (getting and building Geronimo) somewhere under section 6 on development (perhaps Developing Apache Geronimo). I think that most users will begin with our pre-built assemblies and may never see a need to build Geronimo themselves. Under section 3.2 I would include information on choosing a Geronimo assembly, obtaining it, and leveraging the pre-built server. We should also mention the possibility of custom built assemblies and appropriate pointers if they choose to either create their own server using the customer server features or go hog wild and build a unique server image directly using maven (in which case they would need to understand how to build a G server from our source). 2) Consider moving the extensible administration console sections (4.8) under development as well. Also, like Jacek, I would like to harness your enthusiasm to seed the 2.2 content (with a new structure) from the 2.1 documentation. I think that would be a great help to get the 2.2 documentation effort off the ground. Thanks, Joe wei zhang wrote: Hi folks, Changes are not always bad. We are making changes every day, aren't we? The world is always dynamic. : ) We did a scenario based task analysis, and tried to organize the topics in a way that reflects the work flow that users adopt to complete certain tasks with Geronimo. We tried to organize the topics from the users' perspective and make the information more easy to use and easy to find. Quality technical information claims good organization. We also prefer the information center based approach because Geronimo users are mostly developers and it's hard to differentiation one from the other. Take the original user's guide for example, tools and commands are discussed separately in GShell, Tooling, and Administration. However, these tools and commands are also used elsewhere. The Tools and commands topic is placed under Administration, while some commands will not be used until the users do deployment. So, separating this topic from Administration as reference information makes more sense. What's more, some topics in the user's guide seem not to be at the appropriate level, for example, the Clustering topic might go well under Configuring Geronimo instead of standing out. As for the original Developer's Guide, the Tutorial section is not supposed to be placed inside a Developer's Guide as the two are different types of information. And, the information in the Tutorial section is ordinary tasks that developers can perform. The primary function of tutorial information is to move the user's skill set from their current expertise to a more experienced level. Often, this information functions as an introduction to a solution or product that centers on the user's acquisition of general product knowledge and practice. Unlike Wizards or UA task topics, however, a tutorial's main purpose is to create understanding about the concepts supporting a technology or a product, and so to teach fundamental distinctions, skills and heuristic approaches to using the software more effectively. We changed the original Tutorial part to a section that contains specific tasks developers can perform: 6.2 Developing applications for Geronimo 6.2.1 Getting familiar with the development environment 6.2.1.1 http://6.2.1.1 Configuring Application Specific Logging with Log4j 6.2.1.2 http://6.2.1.2 Preparing to run SQL statements at Deployment Time 6.2.1.3 http://6.2.1.3 Locating your application specific configuration files 6.2.1.4 http://6.2.1.4 Quick Debugging JSPs of your application 6.2.1.5 http://6.2.1.5 Deploying applications using the Geronimo Eclipse Plugin (GEP) 6.2.2 Developing Web applications with GEP 6.2.2.1 http://6.2.2.1 Creating a Dynamic Web project using Eclipse 6.2.2.2 http://6.2.2.2 Developing Web applications for accessing EJB 6.2.2.3 http://6.2.2.3 Developing Web applications for accessing JDBC 6.2.2.4 http://6.2.2.4 Developing Web applications for accessing JMS 6.2.2.5 http://6.2.2.5 Developing JavaServer faces applications 6.2.2.5.1 Basics of JavaServer Faces 6.2.2.5.2 Developing AJAX with JSF applications in GEP 6.2.2.5.3 Using JSP immediate expressions to access JSF
Re: Documentation of new 2.2 features in current wiki?
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
Re: Documentation of new 2.2 features in current wiki?
Hi Rebekah, I just posted a note about a new space that I created for the 2.2 documentation. The new space was really created just to get things moving for 2.2. It was not a statement of what the final structure should be ... so please feel free to continue to explore this area and receive comments. I personally haven't had a chance to consider the alternatives you presented below. However, my inclination is to keep the current structure as is unless there are obvious problems with the organization and there are resources willing to invest the time and effort to change things. Can you provide some more information on what is driving the changes that you are proposing? Thanks, Joe wei zhang wrote: Hi there, This is Rebekah and I've been reading through the documentation with my colleagues for a while. I think we can keep the current version of the documentation and create another space for v2.2, because there will be users who may want to track the previous information. Regarding the organization of information, we have worked out new documentation structures based on the 2.1 info using two different appraches: one is pretty much book based, keeping some of the current lookfeel; the other is info center based. If we are going to create a new space for v2.2, we can take either approach. As long as the structure is ready, people can take topics they are interested in and write up the content. If you have any ideas or comments on the proposed structures, feel free to let me know. Thanks. Information center based approach (all in one): 0 Geronimo information 1 What's new 1.1 New features 1.1.1 Custom server assemblies 1.1.2 Geronimo administration console 1.1.3 GShell 1.1.4 Clustering 1.1.5 Monitoring console plugin 1.1.6 Plan Creator 1.2 Enhanced features 1.2.1 Geronimo distributions 1.2.2 Configuration changes 1.3 Compatibility with earlier versions 2 Getting started with Apache Geronimo 2.1 Getting the software 2.1.1 Geronimo directory structure 2.2 Starting the server 2.3 Creating and deploying a sample application 3 Planning and installing 3.1 Installing prerequisite software 3.2 Getting Geronimo 3.2.1 Building Geronimo from source 3.2.1.1 http://3.2.1.1 Building Geronimo with Maven 3.2.1.2 http://3.2.1.2 Building Geronimo from Eclipse 3.3 Installing Geronimo 3.3.1 Installing Geronimo from binaries 3.4 Initial configuration 3.4.1 Available configuration files 3.4.2 Changing the default port numbers 3.4.3 Changing the username and password 3.5 Starting and stopping the server 3.5.1 Starting and Stopping Geronimo in GShell 3.6 Running Geronimo as a non-root user 3.7 Running multiple Geronimo instances 3.8 Running Geronimo as a Windows, or UINX service 4 Configuring and administering 4.1 Deploying and and administering assets in Geronimo 4.1.1 Deploying assets 4.1.1.1 http://4.1.1.1 Deploying assets via the administration console 4.1.1.2 http://4.1.1.2 Deploying assets from the command prompt 4.1.1.3 http://4.1.1.3 Deploying assets via GShell 4.1.1.4 http://4.1.1.4 Performing clustered deployment 4.1.1.5 http://4.1.1.5 Deploying plugins 4.1.1.6 http://4.1.1.6 Performing hot deployment 4.1.2 Administering applications 4.1.2.1 http://4.1.2.1 Installing and removing applications 4.1.2.2 http://4.1.2.2 Starting and stopping application modules 4.2 Configuring and administering the Apache Geronimo Server 4.2.1 Administering Geronimo using the Geronimo administration console 4.2.2 Administering Geronimo using command line tools 4.2.3 Add new listeners for Web containers 4.2.4 Aliasing modules 4.2.5 Configuring virtual host 4.2.5.1 http://4.2.5.1 Configuring virtual host in Jetty 4.2.5.2 http://4.2.5.2 Configuring virtual host in Tomcat 4.2.6 Configuring a remote Apache HTTP server 4.2.7 Configuring JAX-WS engine 4.2.8 Clustering 4.2.8.1 http://4.2.8.1 Farming 4.2.8.2 http://4.2.8.2 WADI clustering 4.2.9 Custom server assemblies 4.2.9.1 http://4.2.9.1 Plugin basics 4.2.9.2 http://4.2.9.2 Buidling,installing plugins and extracting a server from an exsiting server 4.2.9.3 http://4.2.9.3 Assembling a server using Maven 4.3 Congifuring services 4.3.1 Configuring multiple repositories 4.3.2 Adding archives to the Geronimo repository 4.3.3 Configuring database pools 4.3.4 Configuring JMS 4.4 Administering security 4.4.1 Basic Hints on Security Configuration 4.4.2 Configuring JavaEE application client security 4.4.3 Configuring login modules 4.4.4 Configuring run-as and Default Subjects, and
Re: Documentation of new 2.2 features in current wiki?
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 [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
Re: Documentation of new 2.2 features in current wiki?
Resending somehow this never came through the first time: Hi Rebekah, I just posted a note about a new space that I created for the 2.2 documentation. The new space was really created just to get things moving for 2.2. It was not a statement of what the final structure should be ... so please feel free to continue to explore this area and receive comments. I personally haven't had a chance to consider the alternatives you presented below. However, my inclination is to keep the current structure as is unless there are obvious problems with the organization and there are resources willing to invest the time and effort to change things. Can you provide some more information on what is driving the changes that you are proposing? Thanks, Joe wei zhang wrote: Hi there, This is Rebekah and I've been reading through the documentation with my colleagues for a while. I think we can keep the current version of the documentation and create another space for v2.2, because there will be users who may want to track the previous information. Regarding the organization of information, we have worked out new documentation structures based on the 2.1 info using two different appraches: one is pretty much book based, keeping some of the current lookfeel; the other is info center based. If we are going to create a new space for v2.2, we can take either approach. As long as the structure is ready, people can take topics they are interested in and write up the content. If you have any ideas or comments on the proposed structures, feel free to let me know. Thanks. Information center based approach (all in one): 0 Geronimo information 1 What's new 1.1 New features 1.1.1 Custom server assemblies 1.1.2 Geronimo administration console 1.1.3 GShell 1.1.4 Clustering 1.1.5 Monitoring console plugin 1.1.6 Plan Creator 1.2 Enhanced features 1.2.1 Geronimo distributions 1.2.2 Configuration changes 1.3 Compatibility with earlier versions 2 Getting started with Apache Geronimo 2.1 Getting the software 2.1.1 Geronimo directory structure 2.2 Starting the server 2.3 Creating and deploying a sample application 3 Planning and installing 3.1 Installing prerequisite software 3.2 Getting Geronimo 3.2.1 Building Geronimo from source 3.2.1.1 http://3.2.1.1 Building Geronimo with Maven 3.2.1.2 http://3.2.1.2 Building Geronimo from Eclipse 3.3 Installing Geronimo 3.3.1 Installing Geronimo from binaries 3.4 Initial configuration 3.4.1 Available configuration files 3.4.2 Changing the default port numbers 3.4.3 Changing the username and password 3.5 Starting and stopping the server 3.5.1 Starting and Stopping Geronimo in GShell 3.6 Running Geronimo as a non-root user 3.7 Running multiple Geronimo instances 3.8 Running Geronimo as a Windows, or UINX service 4 Configuring and administering 4.1 Deploying and and administering assets in Geronimo 4.1.1 Deploying assets 4.1.1.1 http://4.1.1.1 Deploying assets via the administration console 4.1.1.2 http://4.1.1.2 Deploying assets from the command prompt 4.1.1.3 http://4.1.1.3 Deploying assets via GShell 4.1.1.4 http://4.1.1.4 Performing clustered deployment 4.1.1.5 http://4.1.1.5 Deploying plugins 4.1.1.6 http://4.1.1.6 Performing hot deployment 4.1.2 Administering applications 4.1.2.1 http://4.1.2.1 Installing and removing applications 4.1.2.2 http://4.1.2.2 Starting and stopping application modules 4.2 Configuring and administering the Apache Geronimo Server 4.2.1 Administering Geronimo using the Geronimo administration console 4.2.2 Administering Geronimo using command line tools 4.2.3 Add new listeners for Web containers 4.2.4 Aliasing modules 4.2.5 Configuring virtual host 4.2.5.1 http://4.2.5.1 Configuring virtual host in Jetty 4.2.5.2 http://4.2.5.2 Configuring virtual host in Tomcat 4.2.6 Configuring a remote Apache HTTP server 4.2.7 Configuring JAX-WS engine 4.2.8 Clustering 4.2.8.1 http://4.2.8.1 Farming 4.2.8.2 http://4.2.8.2 WADI clustering 4.2.9 Custom server assemblies 4.2.9.1 http://4.2.9.1 Plugin basics 4.2.9.2 http://4.2.9.2 Buidling,installing plugins and extracting a server from an exsiting server 4.2.9.3 http://4.2.9.3 Assembling a server using Maven 4.3 Congifuring services 4.3.1 Configuring multiple repositories 4.3.2 Adding archives to the Geronimo repository 4.3.3 Configuring database pools 4.3.4 Configuring JMS 4.4 Administering security 4.4.1 Basic Hints on Security Configuration 4.4.2 Configuring JavaEE application client security 4.4.3 Configuring login
Re: Documentation of new 2.2 features in current wiki?
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 [EMAIL PROTECTED] 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 [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
--
~Jason Warner
Re: Documentation of new 2.2 features in current wiki?
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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [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
Re: Documentation of new 2.2 features in current wiki?
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 [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
Re: Documentation of new 2.2 features in current wiki?
This is some great information Dave. Thanks for the details. I experimented a little with export/restore but without much success. I wasn't able to restore an image with an updated entities.xml (that simply replaced the old space references with new space references). Each time I attempted to restore it always complained that the exportDescriptor.properties was either missing or invalid ... but when I checked the file did exist and I didn't see anything obvious in there that needed to be changed when the space name was updated (actually, it only has something like 3 lines that were exportType, buildnumber, and backupattaachements). It is really too bad that we can move an entire page tree but can only copy individual pages. If only we could do that then it would be easy to integrate the 2.1 documents into a 2.2 space that was partially complete. Joe David Blevins wrote: On Jul 31, 2008, at 12:20 AM, David Jencks wrote: My impression based on gossip is that while it's possible to copy an entire wiki space it isn't possible to move individual pages between spaces. Is this correct? On Jul 31, 2008, at 3:38 PM, David Jencks wrote: 3. Create a new space for Apache Geronimo 2.2 (similar to the spaces we have for 1.0, 1.1, 1.2, 2.0, and 2.1). Add new documents specific to 2.2 into this new space. It would be fairly sparse for now. When we complete the 2.1 docs we can clone them into the 2.2 space and integrate the 2.2 specific documents into the appropriate sections/structure. My impression from the 2.1 debacle of not starting by copying the existing documentation into a new 2.1 space was that after the space was created, you couldn't copy stuff from another space en mass. Hopefully I'm wrong. Anyway this hopefully mis-understanding is the basis for (1). What confluence can do: MOVE A PAGE AND IT'S CHILDREN - From a page's Edit tab, click the smaller edit link by Location. You can then change the space or parent page. If you select a new space, a checkbox becomes available that allows you to optionally change the space of all children pages. - Cascades to children: optional - Retains edit history: yes - Retains attachments: yes - Retains comments: yes - Retains labels: yes - Retains permissions: yes COPY A PAGE - From a page's Info tab, click the Copy link. You get a new edit screen with the current page content and a the title with Copy of prepended to it. All the normal things can be edited from this screen, including Location. - Cascades to children: no - Retains edit history: no - Retains attachments: yes - Retains comments: no - Retains labels: no - Retains permissions: no EXPORT / RESTORE - From a space's Advanced tab, click Export Space. You can select any pages you want and export as XML. Then you need to crack open the zip downloaded and exit the entities.xml to change the space name. Zip the whole thing up again and use the Restore option as a confluence administrator. Note you cannot use the restore option on spaces that already exist. - Retains edit history: yes - Retains attachments: yes - Retains comments: yes - Retains labels: no (didn't work for me) - Retains permissions: yes My thoughts: If we really want a separate space for each major version, then I'd recommend we use the EXPORT/RESTORE option to seed from the prior version's space (2.1). If we need to create any pages before then, which seems to be our current dilemma, then we can create a 2.2 page somewhere else (say DEV or SANDBOX or anywhere) and make all such new content a child of that page. Whenever we do eventually create a 2.2 space we can move then 2.2 page and all it's children from the temporary space to the 2.2 space in one operation. The two main reasons: 1. I think author/revision history is critical for oversight. 2. Efficiency. If N is the number of pages we have from the the prior version's space and X is the number pages that are new for the current version's space, N is going to always get bigger and bigger and more and more disproportionate to X. Mathematically starting with a space seeded from the N pages and moving in X pages requires less operations than starting with a new space for X and copying in N pages, which will only get worse over time. Further, the cost of moving X can be reduced to 1 if we use the parent page and move children trick. I understand that one of the motivations for starting blank and copying pages individually was to allow for review of the pages to see if they are still relevant. That's an orthogonal argument as a review process of review then copy would take an equal amount of time as a review then delete process. The real difference is in weather or not pages should be considered relevant or outdated by default and which risk is worse; the potential for missing valid documentation or the potential for present
Re: Documentation of new 2.2 features in current wiki?
Agree. -Donald 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. 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 smime.p7s Description: S/MIME Cryptographic Signature
Re: Documentation of new 2.2 features in current wiki?
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
Re: Documentation of new 2.2 features in current wiki?
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 smime.p7s Description: S/MIME Cryptographic Signature
Re: Documentation of new 2.2 features in current wiki?
On Jul 31, 2008, at 12:54 PM, Joe Bohn wrote: David Jencks wrote: On Jul 30, 2008, at 6:46 PM, Kevan Miller wrote: On Jul 29, 2008, at 6:25 PM, David Jencks wrote: On Jul 29, 2008, at 2:06 PM, 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. OK, but who exactly is going to do all this wiki maintenance that you are proposing? I suggest mixing the docs because I don't think it will be confusing with prominent enough labels and I don't think that wiki maintenance is going to happen, no matter how many good intentions people now have. Furthermore I would much rather that anyone with the knowledge to organize the documentation and interest in working on it spend it on content rather than continual reorganization. I agree with Jarek. I'd prefer that we keep 2.1 and 2.2 content separated. We've still got G 1.1 users. I don't see how a documentation super-set is going to be viable, in the long term. At some point, the documentation would need to be separated. Better, I think, to start out that way and keep things cleaner for 2.1 users. If the 2.1 docs are complete I suggest we immediately copy them to a set of 2.2 docs and I will happily document new features there. If not we need a plan. I think there have been two basic ideas so far: 1. put new 2.2 docs go into http://cwiki.apache.org/GMOxDEV. A quick glance suggests this is currently mostly a combination of advice on how to develop geronimo and documentation that applies to released versions of geronimo such as 2.0 and 2.1. I don't see any reason so far to think that this will be maintained better in the future and stuff moved from here to appropriate versioned docs. How would this work? 2. Add 2.2 docs to the current 2.1 docs, clearly marked as for 2.2 and later. If and when we copy the 2.1 docs to a 2.2 branch, we can remove these pages from the 2.1 docs and remove the since notices. 3. Create a new space for Apache Geronimo 2.2 (similar to the spaces we have for 1.0, 1.1, 1.2, 2.0, and 2.1). Add new documents specific to 2.2 into this new space. It would be fairly sparse for now. When we complete the 2.1 docs we can clone them into the 2.2 space and integrate the 2.2 specific documents into the appropriate sections/structure. My impression from the 2.1 debacle of not starting by copying the existing documentation into a new 2.1 space was that after the space was created, you couldn't copy stuff from another space en mass. Hopefully I'm wrong. Anyway this hopefully mis-understanding is the basis for (1). thanks david jencks I can look into what would be necessary to create the 2.2 space and add a link to it on along side the other 5 releases. Joe My impression based on gossip is that while it's possible to copy an entire wiki space it isn't possible to move individual pages between spaces. Is this correct? If so IMNSHO (1) will never work with confluence. If not I think there's at least one page I'd like to move instructions would be great. Anyone have another idea? thanks david jencks --kevan
Re: Documentation of new 2.2 features in current wiki?
On Jul 31, 2008, at 12:20 AM, David Jencks wrote: My impression based on gossip is that while it's possible to copy an entire wiki space it isn't possible to move individual pages between spaces. Is this correct? On Jul 31, 2008, at 3:38 PM, David Jencks wrote: 3. Create a new space for Apache Geronimo 2.2 (similar to the spaces we have for 1.0, 1.1, 1.2, 2.0, and 2.1). Add new documents specific to 2.2 into this new space. It would be fairly sparse for now. When we complete the 2.1 docs we can clone them into the 2.2 space and integrate the 2.2 specific documents into the appropriate sections/structure. My impression from the 2.1 debacle of not starting by copying the existing documentation into a new 2.1 space was that after the space was created, you couldn't copy stuff from another space en mass. Hopefully I'm wrong. Anyway this hopefully mis-understanding is the basis for (1). What confluence can do: MOVE A PAGE AND IT'S CHILDREN - From a page's Edit tab, click the smaller edit link by Location. You can then change the space or parent page. If you select a new space, a checkbox becomes available that allows you to optionally change the space of all children pages. - Cascades to children: optional - Retains edit history: yes - Retains attachments: yes - Retains comments: yes - Retains labels: yes - Retains permissions: yes COPY A PAGE - From a page's Info tab, click the Copy link. You get a new edit screen with the current page content and a the title with Copy of prepended to it. All the normal things can be edited from this screen, including Location. - Cascades to children: no - Retains edit history: no - Retains attachments: yes - Retains comments: no - Retains labels: no - Retains permissions: no EXPORT / RESTORE - From a space's Advanced tab, click Export Space. You can select any pages you want and export as XML. Then you need to crack open the zip downloaded and exit the entities.xml to change the space name. Zip the whole thing up again and use the Restore option as a confluence administrator. Note you cannot use the restore option on spaces that already exist. - Retains edit history: yes - Retains attachments: yes - Retains comments: yes - Retains labels: no (didn't work for me) - Retains permissions: yes My thoughts: If we really want a separate space for each major version, then I'd recommend we use the EXPORT/RESTORE option to seed from the prior version's space (2.1). If we need to create any pages before then, which seems to be our current dilemma, then we can create a 2.2 page somewhere else (say DEV or SANDBOX or anywhere) and make all such new content a child of that page. Whenever we do eventually create a 2.2 space we can move then 2.2 page and all it's children from the temporary space to the 2.2 space in one operation. The two main reasons: 1. I think author/revision history is critical for oversight. 2. Efficiency. If N is the number of pages we have from the the prior version's space and X is the number pages that are new for the current version's space, N is going to always get bigger and bigger and more and more disproportionate to X. Mathematically starting with a space seeded from the N pages and moving in X pages requires less operations than starting with a new space for X and copying in N pages, which will only get worse over time. Further, the cost of moving X can be reduced to 1 if we use the parent page and move children trick. I understand that one of the motivations for starting blank and copying pages individually was to allow for review of the pages to see if they are still relevant. That's an orthogonal argument as a review process of review then copy would take an equal amount of time as a review then delete process. The real difference is in weather or not pages should be considered relevant or outdated by default and which risk is worse; the potential for missing valid documentation or the potential for present invalid documentation. But as I say, the amount of time to review and remedy is the same, though I do think that users are more likely to help point out invalid documentation that we can delete or update than they are to help review and copy valid documentation. As large as this email is, it's not necessarily complete. The question of when do we really need a new base for documentation is an important one. Is there enough change between 2.1 and 2.2 to merit a new space or can that be delated till later? -David
Re: Documentation of new 2.2 features in current wiki?
On Jul 30, 2008, at 6:46 PM, Kevan Miller wrote: On Jul 29, 2008, at 6:25 PM, David Jencks wrote: On Jul 29, 2008, at 2:06 PM, 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. OK, but who exactly is going to do all this wiki maintenance that you are proposing? I suggest mixing the docs because I don't think it will be confusing with prominent enough labels and I don't think that wiki maintenance is going to happen, no matter how many good intentions people now have. Furthermore I would much rather that anyone with the knowledge to organize the documentation and interest in working on it spend it on content rather than continual reorganization. I agree with Jarek. I'd prefer that we keep 2.1 and 2.2 content separated. We've still got G 1.1 users. I don't see how a documentation super-set is going to be viable, in the long term. At some point, the documentation would need to be separated. Better, I think, to start out that way and keep things cleaner for 2.1 users. If the 2.1 docs are complete I suggest we immediately copy them to a set of 2.2 docs and I will happily document new features there. If not we need a plan. I think there have been two basic ideas so far: 1. put new 2.2 docs go into http://cwiki.apache.org/GMOxDEV. A quick glance suggests this is currently mostly a combination of advice on how to develop geronimo and documentation that applies to released versions of geronimo such as 2.0 and 2.1. I don't see any reason so far to think that this will be maintained better in the future and stuff moved from here to appropriate versioned docs. How would this work? 2. Add 2.2 docs to the current 2.1 docs, clearly marked as for 2.2 and later. If and when we copy the 2.1 docs to a 2.2 branch, we can remove these pages from the 2.1 docs and remove the since notices. My impression based on gossip is that while it's possible to copy an entire wiki space it isn't possible to move individual pages between spaces. Is this correct? If so IMNSHO (1) will never work with confluence. If not I think there's at least one page I'd like to move instructions would be great. Anyone have another idea? thanks david jencks --kevan
Re: Documentation of new 2.2 features in current wiki?
David Jencks wrote: On Jul 30, 2008, at 6:46 PM, Kevan Miller wrote: On Jul 29, 2008, at 6:25 PM, David Jencks wrote: On Jul 29, 2008, at 2:06 PM, 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. OK, but who exactly is going to do all this wiki maintenance that you are proposing? I suggest mixing the docs because I don't think it will be confusing with prominent enough labels and I don't think that wiki maintenance is going to happen, no matter how many good intentions people now have. Furthermore I would much rather that anyone with the knowledge to organize the documentation and interest in working on it spend it on content rather than continual reorganization. I agree with Jarek. I'd prefer that we keep 2.1 and 2.2 content separated. We've still got G 1.1 users. I don't see how a documentation super-set is going to be viable, in the long term. At some point, the documentation would need to be separated. Better, I think, to start out that way and keep things cleaner for 2.1 users. If the 2.1 docs are complete I suggest we immediately copy them to a set of 2.2 docs and I will happily document new features there. If not we need a plan. I think there have been two basic ideas so far: 1. put new 2.2 docs go into http://cwiki.apache.org/GMOxDEV. A quick glance suggests this is currently mostly a combination of advice on how to develop geronimo and documentation that applies to released versions of geronimo such as 2.0 and 2.1. I don't see any reason so far to think that this will be maintained better in the future and stuff moved from here to appropriate versioned docs. How would this work? 2. Add 2.2 docs to the current 2.1 docs, clearly marked as for 2.2 and later. If and when we copy the 2.1 docs to a 2.2 branch, we can remove these pages from the 2.1 docs and remove the since notices. 3. Create a new space for Apache Geronimo 2.2 (similar to the spaces we have for 1.0, 1.1, 1.2, 2.0, and 2.1). Add new documents specific to 2.2 into this new space. It would be fairly sparse for now. When we complete the 2.1 docs we can clone them into the 2.2 space and integrate the 2.2 specific documents into the appropriate sections/structure. I can look into what would be necessary to create the 2.2 space and add a link to it on along side the other 5 releases. Joe My impression based on gossip is that while it's possible to copy an entire wiki space it isn't possible to move individual pages between spaces. Is this correct? If so IMNSHO (1) will never work with confluence. If not I think there's at least one page I'd like to move instructions would be great. Anyone have another idea? thanks david jencks --kevan
Re: Documentation of new 2.2 features in current wiki?
Joe Bohn wrote: David Jencks wrote: On Jul 30, 2008, at 6:46 PM, Kevan Miller wrote: On Jul 29, 2008, at 6:25 PM, David Jencks wrote: On Jul 29, 2008, at 2:06 PM, 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. OK, but who exactly is going to do all this wiki maintenance that you are proposing? I suggest mixing the docs because I don't think it will be confusing with prominent enough labels and I don't think that wiki maintenance is going to happen, no matter how many good intentions people now have. Furthermore I would much rather that anyone with the knowledge to organize the documentation and interest in working on it spend it on content rather than continual reorganization. I agree with Jarek. I'd prefer that we keep 2.1 and 2.2 content separated. We've still got G 1.1 users. I don't see how a documentation super-set is going to be viable, in the long term. At some point, the documentation would need to be separated. Better, I think, to start out that way and keep things cleaner for 2.1 users. If the 2.1 docs are complete I suggest we immediately copy them to a set of 2.2 docs and I will happily document new features there. If not we need a plan. I think there have been two basic ideas so far: 1. put new 2.2 docs go into http://cwiki.apache.org/GMOxDEV. A quick glance suggests this is currently mostly a combination of advice on how to develop geronimo and documentation that applies to released versions of geronimo such as 2.0 and 2.1. I don't see any reason so far to think that this will be maintained better in the future and stuff moved from here to appropriate versioned docs. How would this work? 2. Add 2.2 docs to the current 2.1 docs, clearly marked as for 2.2 and later. If and when we copy the 2.1 docs to a 2.2 branch, we can remove these pages from the 2.1 docs and remove the since notices. 3. Create a new space for Apache Geronimo 2.2 (similar to the spaces we have for 1.0, 1.1, 1.2, 2.0, and 2.1). Add new documents specific to 2.2 into this new space. It would be fairly sparse for now. When we complete the 2.1 docs we can clone them into the 2.2 space and integrate the 2.2 specific documents into the appropriate sections/structure. I can look into what would be necessary to create the 2.2 space and add a link to it on along side the other 5 releases. I started to make a space for this but it really isn't ready for use yet. I need to catch up with Hernan to figure out how to get it set up correctly (and/or keep experimenting on my own). Joe My impression based on gossip is that while it's possible to copy an entire wiki space it isn't possible to move individual pages between spaces. Is this correct? If so IMNSHO (1) will never work with confluence. If not I think there's at least one page I'd like to move instructions would be great. Anyone have another idea? thanks david jencks --kevan
Re: Documentation of new 2.2 features in current wiki?
We do have some colleagues here that are interested in getting involved in Geronimo documentation. We have been looking into the documentation structure of v2.1 for some time now, and have generated some interesting thinking on how to improve the information architecture for v2.2. We will present our proposals soon. Hopefully it will be a good start for v2.2. Jack Cai 2008/7/30 David Jencks [EMAIL PROTECTED] On Jul 29, 2008, at 2:06 PM, 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. OK, but who exactly is going to do all this wiki maintenance that you are proposing? I suggest mixing the docs because I don't think it will be confusing with prominent enough labels and I don't think that wiki maintenance is going to happen, no matter how many good intentions people now have. Furthermore I would much rather that anyone with the knowledge to organize the documentation and interest in working on it spend it on content rather than continual reorganization. thanks david jencks 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
Re: Documentation of new 2.2 features in current wiki?
On Jul 29, 2008, at 6:25 PM, David Jencks wrote: On Jul 29, 2008, at 2:06 PM, 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. OK, but who exactly is going to do all this wiki maintenance that you are proposing? I suggest mixing the docs because I don't think it will be confusing with prominent enough labels and I don't think that wiki maintenance is going to happen, no matter how many good intentions people now have. Furthermore I would much rather that anyone with the knowledge to organize the documentation and interest in working on it spend it on content rather than continual reorganization. I agree with Jarek. I'd prefer that we keep 2.1 and 2.2 content separated. We've still got G 1.1 users. I don't see how a documentation super-set is going to be viable, in the long term. At some point, the documentation would need to be separated. Better, I think, to start out that way and keep things cleaner for 2.1 users. --kevan
Documentation of new 2.2 features in current wiki?
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
Re: Documentation of new 2.2 features in current wiki?
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
Re: Documentation of new 2.2 features in current wiki?
On Jul 29, 2008, at 2:06 PM, 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. OK, but who exactly is going to do all this wiki maintenance that you are proposing? I suggest mixing the docs because I don't think it will be confusing with prominent enough labels and I don't think that wiki maintenance is going to happen, no matter how many good intentions people now have. Furthermore I would much rather that anyone with the knowledge to organize the documentation and interest in working on it spend it on content rather than continual reorganization. thanks david jencks 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
