Please before reading this-- I love WP, I love you guys, I think this is one of the best communities around!
Having said that, I feel the rest of this really needs to be said, and I'm trying to say it gently and so I don't hurt any feelings or anything. But my frustration level with this issue is high right now. Please take that into consideration as you read, and don't take anything personally. And TRY to understand what I'm saying and where it's coming from.
Respectfully, if the upgrade instructions were "fairly clear" I think there would be less posts on the support board from people with frustrations that are the result of following them. I'm fairly good at following clear instructions, and I'm pretty good with xhtml/css and with making edits to php and an occasional change in that code, though php isn't my strongest talent. I install scripts all the time. I even make the occasional minor edit to them. I design small business websites for bucks. I'm not a noob.
I read the instructions in the codex on the "Upgrading WordPress" page. Clear instructions are not at all what I'm seeing, so consequently I'm really not wanting to do this upgrade. If I feel this way, how do you think a noob must feel? Directions for "major" and "minor" upgrade are all mixed up in the "detailed" part of that page with no mention of version numbers, and it's easy for people to misunderstand. Version numbers are all so similar and not spelled out clearly so you have a clear path to follow. I know for a fact I don't understand.
You say, "I encourage you to help us improve the upgrade documentation." Help with the docs? How can anyone do that when they can't understand them? I know they need edits. I'm telling you they need edits. But I'm not qualified to do them. I'll be damned if I do and cause someone else the same frustration I'm feeling.
Meanwhile I'm seeing a lot of posts on this support forum from people who do the upgrade (major? minor? who knows?) and have problems with permalinks (Oh no! Not that! It took me ages the first time!) and rss feeds after upgrading. Why is that information on dealing with that in the wake of the upgrade not in the Codex on that upgrade page, where it will be easy for people to find? The issues keep coming up over and over as a result of this upgrade. I've also gotta wonder if those issues come up because the differences between major and minor and who is supposed to do what are really mixed up in a lot of places.
With so much confusing information I think I'll leave my current install (1.5) up until my host tells me to change it OR until someone edits that "Upgrading WordPress" page so I know what I have to do.
For instance-
Upgrading from 1.<5 to 1.5.1.3
Upgrading from 1.5 to 1.5.1.3
Upgrading from 1.5.1 to 1.5.1.3
Upgrading from 1.5.1.2 to 1.5.1.3 (this one is there, kinda, though mixed in with other stuff)
And maybe leaving out the "major" and "minor" stuff completely. Yes, I know there will be some duplication of material, but if it makes it clearer for people to follow, and lessens the load on the support board, is that a bad thing?
Please help us out here.