Support » Requests and Feedback » CLEARER Written Instructions For Upgrading :-)

  • First, let me emphasize that the following is intended to be a very polite request and some feedback from a new WP user, and nothing more than that. 🙂 I hope I’m in the correct section.

    Here goes. Next time there is an upgrade, can the instructions for upgrading please be written as if the reader is a total beginner? I mean write the upgrade instructions very clearly, step by step, in the exact order in which things should be carried out, and without *assuming* that the reader knows what “delete all your WP files” means (just as one example).

    It would be very helpful, I think, to list the names of the specific WP files, or at least which major directories/folders they are in. Newer users are hesitant to delete things. At least I am.

    Also, sometimes I find the word “root” is pretty confusing; perhaps that could be elaborated upon.

    Another idea: new people are sometimes confused by the use of “index file” because there is more than one index.php file lurking within WP as a whole. I sometimes don’t know which index.php file someone intends to refer to.

    In general, I would like to request more definite and clearly written instructions for *upgrading*. I realize that most people apparently have no trouble with upgrading, but I have not been able to understand which words modified certain parts of some of the sentences; these are just grammatical considerations. I have not upgraded because I don’t feel confident that I understand the instructions, and I don’t want to delete things until I feel that confidence. I hope whoever reads this can understand that.

    Thanks very much for listening. Again, this is meant only as a polite and (I hope) helpful suggestion/request, and nothing more. It is not a criticism of WP or the developers or anyone’s writing skills or anything like that. Really. It’s meant as an honest little piece o’ feedback.

    Thank you. I like WP a lot, in case that isn’t clear.

Viewing 15 replies - 1 through 15 (of 15 total)
  • There is a doc on Codex covering upgrading:

    Perhaps you can comment over there on where changes in it might be helpful. Or even better, get to work on it. ;)

    If I understood what it was trying to say, I would! 🙂

    I have to agree with kay9’s suggestion. After upgrading to 1.5.1 and then being told to upgrade to there was a lack of detail about the upgrade. More detail should be given with regards to upgrading.

    well, since it is the codex, why not update and make more clear the parts that you do understand (which you obviously do to be able to post such a detailed request). this is a community effort, not a one-man show. the updates are really quite simple…especially if you haven’t customized/changed anything outside of your theme directory. i agree that the codex instructions could do with a bit of a clean up and re-orgainzation, but it won’t get done by itself.

    Mark (podz)


    Support Maven

    It’s on my ‘list of things to do’ wrt to WP, but I’m not prepared to hold myself to a deadline.

    Register at codex and if at the very least you could add something to the ‘discussion’ tab there it would assist an eventual rewrite.

    With all due respect and total understanding toward newbies (since we all were newbies at a certain point in time)…
    When we decide to have a website (be it “just” a simple blog) we start a long journey of learning a little bit of webmastering. So knowing what the “root” is or trying to understand the directory and file structure on a webserver (which is BTW, very, very similar to the directory and file structure of your own computer!) are some basic notions that you would need anyway if you lurke around the net and computers 🙂 As for being afraid to delete things, that’s why every good guide starts with “backup your existing files”. Believe me, you don’t have to become a pro over the night to handle some basic notions, it just take a little bit of willingness to learn.

    P.S. This is not to say that the instructions and guides are always user-friendly toward the newbies. But you can help by giving feedback (you just did) and/or if you will ever try to upgrade you could document your steps in lay terms and we would have maybe a better guide 🙂

    I took a serious look at Upgrading WordPress and Installing WordPress in the WordPress Codex.

    I added a few minor steps and clarifications that might make the process easier, and cleaned up the document to look “easier” to read.

    We are always looking for feedback, as well as help, on the documentation. One of the biggest problems we have is that we can make the documentation as simple as possible, but the sudden assault of new jargon, pressure to do and fix and get it going, the psychological aspect of installing or upgrading software is still one that is hard to overcome.

    One of my mother’s biggest whines in life is people who complain and do nothing. I am much the same. You “did” something by telling us your feelings about the documentation. Now we are “doing” something by responding as best we can. Helping with the WordPress documentation site, the Codex, isn’t hard. We need the help, even for advice, tips, and ideas, if not for actual work.


    Great response Lorelle, you’re a credit to the WP community. Kudos!


    Wow, feedback on my feedback. 🙂

    Like I said, my problem (not criticism, not anything but a little weird feedback) is that I don’t understand what some of the stuff means, exactly. And, call me overly cautious, but I’d prefer to be sure I know what each step means, exactly, BEFORE I begin trying to do the steps (upgrade steps).

    I really like WP. As far as the idea of my editing the Codex upgrade instructions, that kinda made me chuckle. I *am* the blind, so I don’t think I can *lead* the blind. Scary thought, eh?

    Um, a sidenote. Just because I “know” enough to point out what parts of the instructions I don’t understand does NOT mean I ‘understand’ enough to upgrade. A monkey can point to fire and “understand” it’s hot and even go ahead and stick his hand in it (start the upgrade) without understanding anything about what he will suffer and how to fix the third degree burns after he gets burned because he went ahead without understanding that indeed, fire turned out to be not only hot, but capable of inflicting burn wounds. (To torture an analogy, which is my special gift.)

    Thanks for the feedback. Best wishes to all. 🙂

    PS What is the difference between feedback and whining?

    kay9 (and anyone else leery of jumping into the fray in the Codex pages):

    We know not everyone will be able to work on the documentation. Even of those who can, many will feel uncomfortable in MediaWiki’s somewhat arcane methodology. That’s one of the reasons you find a Discussion tab at the top of each page over there. Through that you can provide feedback, suggestions and criticisms (the rare praise is nice to see as well), all of which goes a long way in helping us improve it. And to do this, all one needs is to register an account on Codex; there’s no computer skills test, or an evaluation of your curriculum vitae. We want the help, and we’ll take it any way we can get it.

    PS What is the difference between feedback and whining?

    The former is constructive, the latter is usually when people alleviate responsibility and point there finger saying, “it’s not my fault, it’s yours”. I found your feedback 🙂 constructive and fair. It’s very easy to say you can do this, and you can do that since you seem to know what’s wrong. What works for you may not work for everyone, and although the codex is a collabrative effort I have never touched it simply because I don’t want to step on any virtual toes. There’s a few things that I would like the change, but won’t because someone else can probably do it better – I’m not passing the buck, but it’s sometimes easier to make constructive comments than to know how to achieve a result. Web design would be one example, where a user can comment on what they like and what they don’t, but they would probably have a hard time practically demonstrating the improvements.

    The codex is a great place for information, but its organisation and sometimes even the explanations and examples go a little over my head.

    Having said that, there are areas that are not obligations on WP to cover – such as what is the root. This by definition is usually the same throughout where using WP or your PC. The root is the start folder or drive from which others branch out. The root of WP will be the installation dir for WP. The root of the theme folder would be wp-content/themes/ and so on and so forth.

    I think pages are perhaps one of the most confusing elements – where in some examples Pages and page, or pages are mixed together in such a way it becomes a tea-time puzzle. The codex is a grand bulk of information, but it does need improving – and I do actually see it improving.

    As one example, the examples with conditional statements I found bewildering – it was all cluttered together with far too many tags thrown in for explaination with the content making it more difficult to distinguish. It’s possible that the author feels they need to compress everything in as little space as possible, or lack of time, whatever the case.

    As if this little feedback should die from lack of participation:

    kay9, the following are very simple, very educational articles to help people learn about how WordPress works, the jargon, and procedures:

    Introduction to Blogging
    First Steps with WordPress
    New to WordPress – Where to Start
    Stepping Into Template Tags
    The Loop in Action

    Any way to erase this? I really shouldn’t have started this thread. Coupla people are missing my point. Feedback. Just feedback. Turns out it is quite useless. Hence my request for deletion. Feedback only. Not a request for more Codex links. Thanks anyway. See my very first thread-starting post (above).

    Why delete? Ok, no more links (got that Lorelle!), but the thread covers some good points. You’ve highlighted something important here, so let’s not hide it. ;)

    Usability is a priority for WP development. For evidence of this, see:
    Given this priority, posts such as the one that started this thread seem very valuable. Thanks, kay9, for initiating this discussion.

Viewing 15 replies - 1 through 15 (of 15 total)
  • The topic ‘CLEARER Written Instructions For Upgrading :-)’ is closed to new replies.