[documentation] Re: Upgrading docs

[Charlie Lowe]

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