Re: Documentation of new 2.2 features in current wiki?

[David Jencks <da...@yahoo.com>]

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?

[Joe Bohn <jo...@earthlink.net>]

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 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?

[David Blevins <da...@visi.com>]

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