Unhappy with the upgrade instructions and complex process!

[avian]

I just spent several hours trying to update my Zen Cart 1.3.9h to 1.5. The instructions on this site are extremely cryptic. I am very close to giving up on Zen Cart altogether. I realize this is a free software, so I shouldn't expect too much, but come on, someone needs to explain things a little more clearly please and explain things for more than one scenario.

I have my Zen Cart installed in the root folder. The instructions seem to be only geared for those people who have Zen Cart installed in a subdirectory.

I see other people are having problems too, why can't the instructions be more clear and/or the process be more simple in the first place?

I followed the instructions, but then during the database upgrade I got 4 skipped upgrade statements, then I got 25. The whole process failed apparently because when I was finally able to log in to the "new" site, it said I was still at 1.3.9h.

The REALLY frustrating part of this process was due to the difficulty in deleting and/or moving the protected files on the server. Every folder has to be opened and the files unprotected before deleting them. It takes FOREVER!

I installed 1.3.9h originally with the Dreamhost one click install.

Help!

[gjh42]

There's nothing significantly different about installing Zen Cart in the root or in a subfolder, except that there is a little more to keep aware of in a subfolder.

Rather than just saying "why can't the instructions be more clear", why don't you describe the things you found unclear? The only way for instruction writers to know what is confusing to others is for them to tell about it.

I don't encounter protected files that need to be individually altered when upgrading (aside from the two configure.php files), so something about your particular situation or process is apparently causing more work than usual. What you describe does sound tedious.

[avian]

There is a difference obviously, but instead of telling me how to do it, you just tell me it's nothing significantly different, what does that accomplish? It's as if you're keeping it a secret.

If I knew what I had done wrong, I wouldn't have written the post in the first place. I can't tell you how to explain it more clearly if I don't know what is wrong with the instructions, how I ended up doing it wrong. I just think that whoever wrote those instructions isn't taking into consideration that some of us have no idea how to do it, have never done this type of upgrade before and cannot read between the lines. Each sentence needs to be complete, concise and clear. It's also very insulting that the instructions say how easy it is.

The problem with the protected files was with deleting the files that didn't work, not with uploading them. To move the files from a folder to the root would have caused the same issue, I think.

I'll make some notes in bold after these instructions to illustrate my point.


Back up your site from the server as well as the copy on your computer.
Backup your database
Create a new directory and copy your site into it
Then create a new database and load your old database in it
Next, change the two configure.php files to utilize the new directory and database (How should they be changed, which two configure files, from the old or new files or ?)
This way ... when you attempt to upgrade you are "practicing" to see where the problems, if any will happen (practicing on what?)
Make sure all appears to be working on your temp site.
Now load the "new" version files to your new temp directory (from latest downloaded ZIP) (What new temp directory?)
Run the http://www.your_domain_name.com/your...ite/zc_install
Choose the Upgrade Database option
Process each suggested step one at a time ... leave the first checkbox that the upgrader picked checked and uncheck the others. (Why do I have to uncheck them, why are they checked in the first place? I may have missed this step BTW)
-Advantage is that you can see your problems step by step
-Each time it completes it will recheck the boxes left to go. (What?)
-Continue in this method until all boxes are unchecked.
If you find you have issues, you are not hurting anything and can always start over without damage to your existing shop and live database. (Except that it will take hours to delete the files.)

[gjh42]

The only difference I can think of at the moment is that you have to remember and use the subfolder name if you have one.

I found the tutorial you are referring to... why do you think that that is intended to be the main document used by upgraders?

B. If you have NO CUSTOMIZATIONS to preserve, here's a high-level overview/summary of a slightly shorter process:

...

Reminder: Read the /docs/2.readme-upgrade.html document for step-by-step details and information on tools to help in the process.

I understand that "high-level" is not meaningful to non-technical people, but "summary" should be a clue to anyone. If you needed step-by-step details, why did you not follow the reminder to read the documentation?

[avian]

I also had used these instructions: https://www.zen-cart.com/tutorials/i...hp?article=108 and found them equally as frustrating.

[avian]

gjh42, your link: /docs/2.readme-upgrade.html is incomplete.

[avian]

BTW, I volunteer my services if the writers of the Zen Cart 1.5 upgrade instructions need someone who would help them to view their writing from a less technical viewpoint and to point out things like the lack of instructions for installing in the root and the other problems that I encountered. I would prefer to do it privately by email or other means though to avoid it from turning into a public argument which was not my intention when I first posted. The reason I posted regarding this problem was to help in some way, though at the time I was very frustrated because all my hard work did not result in a successful upgrade. I appreciate that Zen Cart is a free software and am willing to do my part to help rewrite the instructions if the writers are interested.

[stevesh]

I can't disagree with your contention that the upgrade instructions could be a lot better, though I have followed them exactly and they do work (although I've been working with Zencart for sometime).

[avian]

Hi stevesh, thank you for joining the discussion.

I would consider writing my own upgrade tutorial if I had been successful with the upgrade. It's a Catch-22 situation though, since I was not successful, I can't write better instructions, but without better instructions, I won't be successful.

I guess I'll wait a while to see if someone else on the net writes better instructions or if Dreamhost will offer some sort of automatic upgrade in the future. If not I may have to switch to a more user friendly platform.

BTW stevesh, do you know how to trash a Zen Cart installation without having to unlock each folder one at a time? I'm on a mac and am using Cyberduck. I did "apply changes recursively" when I changed the file permissions, but it only goes down one level. I had the same problem with the Dreamhost web ftp. If it weren't such a pain to trash the files and start over, I'd be much more interested in giving it another try.

Thanks!

[rstevenson]

Your trash problem sounds like it's with Dreamhost. Perhaps you can tell them what you have to do and ask them to lift the restriction against resetting file permissions for more than one folder deep. Or, perhaps you could go into whatever control panel they offer on their servers and do the delete there rather than through ftp. It would probably be faster that way too.

As for the upgrade instructions, I think a good rule of thumb (rarely followed) is that developers should never be allowed to write instructions. They should write documentation, but that is not the same as instructions. Writing instructions that are clear and complete is a highly specialized task. Recall, as an example, HyperCard. It came with a large set of documentation from Apple, which was almost entirely useless. The books that everyone used to actually accomplish things with HyperCard were The Complete HyperCard Handbook by Danny Goodman, and HyperTalk, The Book by Winkler, Kamins and DeVoto. One was about the product and its use and the other about the underlying language -- they overlapped a lot. My copies were each well-thumbed and marked up, and were absolutely vital.

Rob