[documentation] URGENT: Please review upgrade tutorial instructions

[Kieran Lal]

On Dec 1, 2005, at 3:13 AM, andrew morton wrote:

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

Users are going to do what they want.  It's not really two versions.   
It's more like a menu.   Users will pick and choose which parts of  
the instructions they want to use.  All we can do is present them  
with logical choices.

> 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*.

http://drupal.org/upgrade/basic-steps-via-GUI
The basic steps behind upgrading are:

     * Backup your database and existing Drupal files - this is very  
important!

Is that not enough?


>
> After that, give them the shortest possible version:
> *Something like rename modules directory (so you're not loading old
> contrib modules)

I think it's an all or nothing proposition.  If you don't get all the  
right Drupal core files, but get new modules you are in trouble.

> * Download and extract drupal archive over existing files
> * Run upgrade.php

update.php, I get them confused all the time.

> * Download updated modules.
> Then provide a link to trouble shooting resources to remind them that
> this is the risky way.
>
I am not sure that contributed modules should go in the basic  
instructions.

> Few thinks for the verbose instructions:
> * I'd like to see that duplication between the command line and GUI
> instructions removed.

What do you mean? People who use the GUI instructions have a  
different process than those who use the command line, hence the  
separate instructions.

> * The command line instructions shouldn't be children of the GUI
> instructions, They should be on the same level.

OK, now I get it.  But the book page navigation does not allow this.   
This is why I put the navigation in  the page.

> * The link to "Do I need to upgrade the db?" should be before you tell
> them how to upgrade the db

It already is?  I assume you mean on this page: http://drupal.org/ 
upgrade/basic-steps-via-GUI

Do I need to upgrade my Database?
*Basic Steps behind upgrading without DB Upgrade can be found here

The basic steps behind upgrading are:

     * Backup your database and existing Drupal files - this is very  
important!

> * Clarify when we're referring to the drupal system files, and the  
> contents of the files directory.

Can you point out some examples?

> * There are still lots of CivicSpace references in the command line  
> instructions.

Ok, fixed.  Thanks for pointing them out.

Kieran

> Looking good though,
> andrew
> --
> [ documentation | http://lists.drupal.org/listinfo/documentation ]
>