Modx documentation issue in "Upgrading MODx" section

May I suggest clarifying the documentation regarding upgrading Modx? (rtfm.modx.com/display/revolution20/Upgrading+MODx) I'm guessing a lot of people looking at it are, like me, not at all sure of what they're doing.

So far, under "Uploading the Files" it just says, "For traditional distribution users, simply upload the files over the existing ones, and then run setup."

I would suggest:

1. Providing a link to "the files."
2. Saying something like, "overwrite the existing files in your root folder with the files in the zip from the above link" instead of "upload the files over the existing ones."
3. Putting info about running setup all in one place. Right now it says to run setup, then talks about some other stuff, and finally starts a whole section on the topic. Not a huge deal but...
4. Placing a clear separator between 'traditional' and 'advanced' upgrade processes so that warnings about overwriting files don't appear next to instructions telling you to overwrite files.

I also respectfully submit to BobRay, if you happen to see this, that your page http://bobsguides.com/modx-upgrade-faq.html isn't as helpful as it might have been at one time. Your site is one of the first I hit up when I run into trouble with Modx—it's excellent. Perhaps an update or a link to the official docs might be in order?

I've made some changes to the documentation that better clarifies the upgrade process, added a link to the download page, and clarified the extraction process.

In neither case (adv. or traditional) is overwriting the files acceptable, so I didn't bother to separate the adv. and traditional instructions. It's practically the same process anyway, and the only real difference is where you merge the selected advanced files.

Hope this clarifies the process better.

Thanks for editing it, it's much better already!

I guess I was confused about the effect of "move" in cpanel's file manager (which I used to do the update). It would seem the cpanel file manager just does the right thing when you tell it to move the files from one directory to another—because that's all I did. Can we assume this is the case in general as well as for other file managers? People doing it this way will find your instruction to "merge/copy" a bit vague in terms of execution. But I suspect it's related to my next point...

It's also confusing that the section starts by recommending against using FTP, and then devotes the second half of the section to ...FTP. Is that because you're using an FTP client to move files between directories, merge, etc.? This could be clearer.

As you can see I'm coming at this as a complete novice in terms of dealing with files on a web server! I hope my perspective is useful and not just a pain

I'm hesitant to remove that portion of the docs, as it's been there for a long while and does offer information about FTP use relevant to the process. Some do insist on using FTP despite the warnings, and if they choose to do so it's important information to know.

I always use the copy function in cPanel, although move works just as well. I will take another look and see if I can clarify it a bit more.

Having a novice's perspective is a good thing, and not a pain at all. Those of us who know the process often miss that perspective when working up documentation. It's good to hear what is confusing for those who aren't familiar with the terminology or interfaces so that it can be clarified better for all experience levels.

In other words, thanks!

There is more detailed info here: http://bobsguides.com/modx-upgrade-faq.html.

It's about upgrading, but the method for transferring the files would be the same.