[documentation] Re: Upgrading docs

[Kieran Lal]

On May 1, 2006, at 7:41 AM, Charlie Lowe wrote:

> On the one hand, Kieran is right. This is not a trivial matter of  
> just removing links and maybe shuffling some pages.
>
> On the other hand, I can see a way to do this within the book  
> hierarchy. After all, people write instructional materials like  
> this in print all the time without benefit of hypertext. Right?  
> Doing so requires not just moving pages but reworking how the text  
> is organized.
>
> Here's a rough outline draft. It obviously would be refined during  
> reworking that section of the handbook. Does it make sense?

Ok, anyone else on the docs team available to help re-organize it?

Kieran

> If so, I can work on it this evening.
>
> * Getting started: Assessing resources and backing up
> - Do you have phpmyadmin? Command line via SSH? Why choose one over  
> the other? Using both?
> - Important! Backing up the database and existing files
> -- gui
> -- command line
>
> * Creating a test site or replacing an existing one? Installing new  
> files (downloading Drupal and copying files)
> - existing site
> --gui
> -- command line
> - test site
> -- gui
> -- command line
>
> * Running update.php: Do I need to update the DB?
>
> * Finishing up
> - Configuration options
> - Copying test sites
> - Testing the site
>
> * Upgrade finished.
>
> Kieran Lal wrote:
>> On May 1, 2006, at 1:29 AM, Moshe Weitzman wrote:
>>> If book is getting in the way, don't use it. Create a bunch of  
>>> plain old
>>> pages and hyperlink as you need to.
>> Thanks.  Charlie will weigh in the morning and I'll be on top of  
>> it.  We should have it all worked out by tomorrow.
>> Kieran
>>>
>>>
>>> On 5/1/06 4:20 AM, "Kieran Lal" <kieran at civicspacelabs.org> wrote:
>>>
>>>> On Apr 28, 2006, at 6:10 PM, Moshe Weitzman wrote:
>>>>
>>>>> One nice to have would be if someone would cleanup up the
>>>>> formatting (and copy if you can) of our upgrading docs. They  
>>>>> appear
>>>>> to have been copied and patsed from somewhere and they have their
>>>>> own navigation in addition to
>>>>> book.module navigation. See http://drupal.org/upgrade/tutorial-
>>>>> introduction. I'm not on the docs list - it might be that folks  
>>>>> are
>>>>> working on this already.
>>>>>
>>>> Let me try to explain this the best that I can, you'll undoubtedly
>>>> disagree( I did at first) unless you actually sit down and watch a
>>>> lot of people upgrade Drupal.
>>>>
>>>> There two ways to upgrade Drupal: 1) Command Line, 2) GUI
>>>>
>>>> WRONG
>>>>
>>>> There are four ways to upgrade Drupal: 1) Command line for the  
>>>> files
>>>> and command line for the DB, 2) Command line for the files and GUI
>>>> for the DB 3) GUI for the files and command line for the DB 4) 
>>>> GUI for
>>>> the files and GUI for the DB
>>>>
>>>> WRONG
>>>>
>>>> Well actually there is also upgrades with no DB changes so that  
>>>> adds
>>>> two more cases.  So six cases right?
>>>>
>>>> WRONG
>>>>
>>>> Well actually many people will want to  back up their DB's if it's
>>>> just a security release in so that's actually 8 ways, right?
>>>>
>>>> WRONG
>>>>
>>>> Of course there are people who will just back up and then upgrade
>>>> their live site and check if things go well.  But for productions
>>>> sites, they will actually deploy a test site first so that's  
>>>> another
>>>> factor of 2 ways to upgrade your site, particularly if you test
>>>> locally or on a test server where you have different levels of  
>>>> access
>>>> then on production.  So sixteen ways right?
>>>>
>>>> MAYBE
>>>>
>>>> But overwhelmingly, most people will just upgrade in two steps.
>>>> Download the latest code, and then upgrade the database.  So if the
>>>> instructions are too far away from the way people are actually  
>>>> going
>>>> to upgrade, then they effectively become accurate, but unusable, or
>>>> at least un-used.
>>>>
>>>> What can we do about it?
>>>>
>>>> The problem is that the Book navigation structure on Drupal.org for
>>>> handbooks does not lend itself to at least 16 different paths, and
>>>> one overwhelmingly popular way, through the upgrade tutorial.  It
>>>> wants a hierarchical structure that just will not work for many
>>>> people, but when most people look at the upgrade instructions they
>>>> can only think of one or two ways to upgrade their site, and so  
>>>> they
>>>> immediately want to remove the alternate navigation that seems
>>>> redundant to them.
>>>>
>>>> So feel free to change the navigation,  but keep in mind  
>>>> upgrading is
>>>> a lot more complex and varied than you might initially think.
>>>>
>>>> Cheers,
>>>> Kieran
>>>>
>>>>
>>>
>>>
>>>
>