Re: Upgrading docs

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@xxxxxxxxxxxxxxxxxx> 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

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/