[documentation] URGENT: Please review upgrade tutorial instructions

[Liza Sabater]

Hear ye, hear ye ---Words from an Upgrade Weenie :

(1) FEAR AND LOATHING
My panic attacks about upgrading is that when I see this kind of  
documentation all I can think of is : WTF!  I have to do a whole  
install of the site I am going to upgrade? You have to realize that  
getting everything on the site up and running in the first place was  
a major pain and hassle. You are go through the same agony and  
suffering again. URGH! I need a paper bag or maybe an inhaler.

So I need a document that will literally hold my hand and tell me  
everything is going to be ok. I like the tone Kieran has used here.  
The information though has to be broken down into

(2) BABY STEPS
The way this is organized is a bit daunting, I have to agree. I'd  
take the items 1 through 7 that you have here :
http://drupal.org/upgrade/basic-steps-via-GUI

And put them as far up on the book as possible. That would mean that  
instead of having the GUI side-by-side the COMMAND-LINE version, I'd  
have these both as separate headers:

UPGRADING FROM PREVIOUS VERSIONS

-- USING COMMAND-LINE 
* PRE-UPGRADE TIPS
* STEP-BY STEP AT TEST SITE
**step 1
**step 2
**step etc
* HOW-TO DO/COPY TO LIVE SITE
**testing
* ALL TIPS AND STEPS IN ONE PAGE


--USING FTP and PHPADMIN
* PRE-UPGRADE TIPS
* STEP-BY STEP AT TEST SITE
**step 1
**step 2
**step etc
* HOW-TO DO/COPY TO LIVE SITE
**testing
* ALL TIPS AND STEPS IN ONE PAGE

--POST UPGRADE TIPS and whatever other words of wisdom you have in  
store for me, the user, because, really, this is all about ME THE  
USER :)

And that's it. Maybe you could organize it a bit differently but in  
terms of usability, I think this would work.

Best,
liza




On Dec 01 2005, at 11:20, Kieran Lal wrote:

>
> 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 ]
>>
>
> -- 
> [ documentation | http://lists.drupal.org/listinfo/documentation ]
>