[documentation] Re: Upgrading docs

[Kieran Lal]

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