[documentation] URGENT: Please review upgrade tutorial instructions

[andrew morton]

On 12/1/05, Kobus Myburgh <itbjdm at puknet.puk.ac.za> wrote:
> > We designed the tutorial in a way that it was going to provide the
> > two basic steps for everyone, and the advanced steps for those who
> > listen to their teachers, look both ways before crossing the street,
> > and eat their broccoli.
>
> I understand. You have done the research, and the research trumps my gut feeling and personal choice. I'll rest by your decision.
>

I think there are too many steps in the long version, and not enough
in the short one. That, and it's not clear that there are two
versions. I'd put use some wording similar to the "if you eat your
broccoli and look both ways..." use the long/safe instructions, if
you're into living dangerously here's the quick way.

For the abbreviated upgrade, step one really must be "make a backup of
your database and your files directory (okay fine, just the database
you're in that big a hurry)". Even if they ignore it, by mentioning it
sends the message that during the upgrade process *bad things can
happen*.

After that, give them the shortest possible version:
*Something like rename modules directory (so you're not loading old
contrib modules)
* Download and extract drupal archive over existing files
* Run upgrade.php
* Download updated modules.
Then provide a link to trouble shooting resources to remind them that
this is the risky way.

Few thinks for the verbose instructions:
* I'd like to see that duplication between the command line and GUI
instructions removed.
* The command line instructions shouldn't be children of the GUI
instructions, They should be on the same level.
* The link to "Do I need to upgrade the db?" should be before you tell
them how to upgrade the db
* Clarify when we're referring to the drupal system files, and the
contents of the files directory.
* There are still lots of CivicSpace references in the command line
instructions.

Looking good though,
andrew