The JIRA upgrade guide is misleading

A few points:

• A few times it says to set up a second test instance with "Configure your new JIRA to have the same configuration as your old JIRA".
  Actually, it had better point to a different database schema, else all hell will break loose.
  Also it needs a different Lucene index directory.
  These are kind of covered later, but I worry that a user may get confused.
• It tries to explain the "XML upgrade" method, and "DB upgrade" method together, whereas I think each should be explained separately even if this means some duplication.
• Note that the instructions generally refer to setting up a test instance on the same box as the prod instance. It should be noted that better practice is to use a separate box if possible.
• It seems to mostly explain setting up a test upgrade, rather actually doing a real upgrade, but it is not clear which is which.
• Section 5.2 "Post-startup checks and tasks", seems to be a mix-up of some final things to do when setting up a test instance, and tasks to change over the test to production.
• "If you changed machines when upgrading, change the paths to the indexes, attachments and backup directories, from within the Administration section of JIRA."
  Actually, if you installed on a different machine, you may be able to use the same directories, however on the same machine you will definitely need to change these.