Upgrade documentation can be confusing

Hello, it's me ... again (bury it's head in the sand)
I am sorry if I post too much things thats seems "request" or "critics" or not contributing much, I just feel that it is a way to document the "problems" or "questions" I encounter implementing AEdir for the first time. The goal is to use my "stupid newbie" perspective to document as much as possible the things that are surprising me, in the hope it will help others and help the product get, in the end, less support requests for such tings.
Tell me if I am too picky or going below the intended level of AEgir.

I wanted to upgrade my AEgir 0.3RC4 to 0.3 and tried to read and understand the upgrade.txt document first.

I found it a bit confusing and at time convoluted (because the WHY of doing things was not always clear, and so I feel like I have to do things without really understanding why another route is not used, I'll explain later on)

Confusion ;)

I did find the document confusing because it mixes two things that should be, unless I am mistaken, separated

• migrating AEgir from version to version of itself
• migrating the AEgir hosting system to a new platform (from drupal-6.12 to drupal-6.13)

I think these two issues should be cleanly separated one can happen without the other and they probably should happen independently.

Furthermore a few terms left me doubting about my understanding, mostly because, of course, I am unfamiliar about the whole AEgir machinery and so I can't be sure of the meaning of some terms ..
For instance :

* backup the site
* deploy to a test site
* verify if it works
* delete the old site
* deploy to new site

I can guess that the term "site" apply to the specific hosting site under the drupal-6.x installation excluding eventual other "web sites (hosted)" served by the hosting drupal-6.x installation, but I am left with some doubts if it does not mean the whole Drupal-6.x platform.
Maybe some consistent uses of names like platform, hosting platform, hosted site, hosting site / hostmaster site would help.

Convolution :)

The document seems to hesitate between upgrading and re-installing.
Let me explain :)
For the back-end the doc does not even mention doing a CVS update to join head or stuff like that but recommend a simple re-install ; download the last version of drush and the last provision module in place and be done with it... :)
For the front end the install document try to juggle both the platform upgrade and the front end upgrade ... while accommodating the safety of hosted sites.

For instance, the given script assumes the drush dl drupal will download a different version than the one installed...

Could I resume the main ideas as such ? :

1. Install a new hosting platform (drupal-hosting)
2. install aegir on it pointing to the same DB (or does the drush verify / backup / deploy does a different thing ?)
3. Check it works
4. Install the old hosting platform as a platform under the new hosting platform
5. Migrate the hosted sites on the new hosting platform or another platform if needed

Reading the doc and writing this I can't help thinking than a better recommended structure would help us greatly, reserving a platform only for hosting and not mixing hosted sites with it, I am trying to test the waters on my server about this and will report my ideas about it for due criticism. ;)

PS: selfish question : coming from 0.3RC4 would a "cvs update" on provision and hostmater not do the job ? :)

And thanks again on the great work on AEgir, the stuff is great and promising even more :)