[wp-docs] 5-Step Upgrade in Upgrading WordPress

[Carthik Sharma]

I am not replying to any one question in particular, hence the
top-posting of this reply.

Every operating system/system software has quirk and special cases on
different platforms/user setups. Official documentation should deal
with the most general case, dealing with special cases that are more
troublesome specifically if required. This is the case with all
documentation, everywhere. A windows installation/upgrade guide or
movable type upgrade guide (just examples) do not try to explain how
to install/upgrade it on EVERY system, but instead just focusses on
the steps involved, in general.

In general, the idea behind every WP upgrade is that files need to be
_replaced_. Overwriting is in general, the accepted way of achieving
this. Some setups may require deletion and then uploading -- BUT -
even this is not a solution.

I personally help upgrade around 20+ wp installations. One user who I
help with administration used the previous upgrade guide and dutifully
deleted all the wp-* documents in the root folder except for the
wp-config.php file. His upgrade went poorly, since there was a
subscribe plugin that had a wp-foo.php file in the root folder. This
wouldn't have happened if he had overwritten files, instead of
deleting and upgrading. This is a special case where the
"delete-and-upload" philosophy turned out to be worse than the
"overwrite" approach. Does this make you lean towards "overwrite" now
that you know this? I suppose not.

WP support and documentation are such difficult problems in general
due to the scope that we define for ourselves. A user who does not
know the basics of hosting a website and adminstering a user account
(her own) on a server should not expect to get lessons about the same
from the documentation for a web application! If that hasn't sunk in,
what I am saying is the equivalent of "User documentation for gmail
should not include instructions for installing a browser" and the
like.

There is no reason to feel bad about saying "sorry but that is outside
our ken". The sooner we learn that the better. At least, the official
set of documentation resources should not be crippled by this. Setting
a modest goal (for documentation) is not a crime.

About the upgrade guide - what I wrote was a draft - you can update it
with links to address the problems posed here. Support volunteers can
refer people with upgrade problems to the more detailed guide and
request them to follow that on their restored backup of the
un-upgraded wp install before proceeding further.

What right does Carthik, who does not spend ANY time on the forums
have to lecture us about support, you ask? Well, I have been there,
and I stopped going there from when the number of issues, and the
kinds of user questions I was assumed to be responsible to support
outgrew my interest. Remember - this is all voluntary, and the people
who put the most into support have probably gained more from it than
people who haven't.

Giving up on improving something, and finding an acceptable via-media
compromise is negative. I will take my shot at improving the guide for
which I am responsible now.

Last point -- the usefulness of user documentation approaches zero as
the length of the articles increases beyond reasonable need. Just like
an over-cluttered UI, or too many options, this turns people off,
terribly. So lets keep the essence easily available, and the details
available for only those who need it.


Carthik.

On 2/16/06, TechGnome <tg at tannagh.com> wrote:
> Here's a thought, and call me crazy if you want.... include the delete
> files step in the codex directions.... then as a caveat to that
> direction, include a link to another Codex page that asks and answers
> the question "Q: Why am I told to delete my files." A: Because it has
> been our experince over the last few years that FTP clients are not
> always reliable in actualy overwriting files and some may retain their
> old code. ... etc..."
>
> Just a thought... Could also be x-referenced with the Upgrade FAQ (if
> there is one.)
>
> -tg
>
>
> Michael B wrote:
> > What would be wrong with a 10 minute upgrade, vs a 5 minute.  Is there
> > competition out there that WP is trying to "beat"?  I'd rather give
> > someone more detailed instructions and it have a lower percentage of
> > error, than the short and sweet, and then see their frustration level
> > go through the roof, and start bad mouthing WP for being too "hard",
> > and posting threads, "HELP!!!! UPGRADED VIA CODEX, AND MY BLOG IS
> > BROKEN!!!!!!PLEAZEEEEEE!!!!HELP!!!!!!!!"
> >
> >
> > ------------------------------------------------------------------------
> >
> > _______________________________________________
> > wp-docs mailing list
> > wp-docs at lists.automattic.com
> > http://lists.automattic.com/mailman/listinfo/wp-docs
> >
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>


--
Ph.D. Candidate
University of Central Florida
Homepage: http://carthik.net