[Fixed v1.5.1] 1.5 Implementation Guide Suggestions
Forced to be away from normal work, I got to thinking about a recent problem with the installation of ZC. I recalled my volunteering to assist in the maintenance of guides, tutorials, etc and pulled up the pdf guide for 1.5.0 implementation. Looking through the first seven sections, I came up with a few suggestions and clarifications which I submit with full appreciation of the effort already put into this document.
3. Obtaining the current Zen Cart release -- Pg 6
For consistency, this title shoudl be "Obtaining the Current Zen Cart Release".
4. Unpacking snd Uploading the application software files -- Pg 7
For consistency, this title shoudl be "Unpacking and Uploading the Application Software Files".
4.4 Advanced Method--Pg 7
You can optionally save some time by uploading the zip file directly to your server(using FTP etc.), and unpacking it on your site if your hosting company provides you a means of unzipping files on the server side. Talk to your hosting company about this.
5.1 New Installations--Pg 8
2) configure.php files
Is this really necessary or just a way of confusing those who read this after installing? Numerous posts on the forum are a result of someone renaming the dist- files AFTER installation resulting in a non-working cart. Why not just remove 2) and change 3) to 2).
6.1.4 Step 3 System Inspection -- Pg 14
Since we are still in the midst of installation instructions, would it not be better to have a warning box (like on page 9) stating:
WARNING: If you see an "Upgrade CFG Files" or "Database Upgrade" button at this point, there is data in the database. Clicking on the "Install" button with either "Upgrade" button showing will erase any data in the database. For instructions on doing upgrades...
6.1.5.3 Database Username/Password -- Pg 15 last line add "using"
...it is up to you to change it to something strong and secure, using the tools provided by your hosting company.
6.1.6.2 URL to your Zen Cart store -- Pg 17
For consistency, this title should be "URL to your Zen Cart Store".
6.1.6.3 and 6.1.6.4 might need to be moved to page 17 with the image consisting of only the portion applicable to .3 and .4. Then, make a new page with 6.1.6.5, 6.1.6.6, the warning box, and the last half of the existing image on pag 18.
6.1.6.7 Save System Settings -- Pg 19 Needs to be added
If all the System Settings on this page are correct, click on the "Save System Settings" button to add the system settings to your database.
6.1.7 Step 6 Store Setup -- Pg 19
When any of these items are described as "used to" are we not falsely indicating that there is no need to enter this information elsewhere? Store Owner Email, Store Country, and Zone are simply insertions of database content, not the creation of a variable that will be "used". Store Address on Pg 19 does not have the "used" statement, but does have a correct version of a used statement in the figure on Pg 20.
6.1.7.1 Store Demo -- Pg 21
in built is normally spelled inbuilt but even the definition for inbuilt lists built-in as the first answer. Also "You may find it useful load this demo data so that you can get comfortable with the application, before you actually start to build your own store." should be "You may find it useful to load this demo data so that you can get comfortable with the application before you actually start to build your own store." to be more correct.
6.1.7.2 Save Store Settings -- Pg 21 Needs to be added
If all the Store Settings on this page are correct, click on the "Save Store Settings" button to add the system settings to your database.
6.1.8.1 Administrator's User name -- Pg 22
For consistency, this title shoudl be "Administrator's User Name".
6.1.8.2 TEMPORARY Administrator's Password -- Pg 22 Warning Box rewrite
PA-DSS
You most likely accessed this installation without using SSL. That means there is an extremely
small possibility that someone could have intercepted your admin username/password. Make sure you enable SSL for your admin page. This will cause your admin password to expire and you'll need to select a new password. This helps ensure that, if someone has stolen your password over an unsecured connection, they'll be unable to use that password any longer.
6.1.10 --Pg 23 Change to Save Admin Settings and renumber existing 6.1.10 to 6.1.11 (text for 6.1.10)
If all the Admin Settings on this page are correct, click on the "Save Admin Settings" button to add the system settings to your database.
6.2.4 Step 3 System Inspection -- Pg 26
This does not address which button to select for what action nor is the result of clicking "Upgrade Cfg Files" addressed. Instead, we're taken directly to the result of clicking on "Database Upgrade".
6.2.5 Step 4 Version-upgrade-checkboxes -- Pg 26
As in Step 3, the various options are not addressed and only the result of clicking "Done with Updates" is addressed.
7. Post Installation activities -- Pg 29
For consistency, this title shoudl be "Post-Installation Activities".
7.1 Changing The Admin Directory Name for Security (By-Obscurity) -- Pg 29
Second paragraph, second sentence needs another comma and wordage change to avoid possible focus on "easy to guess". "Therefore, before you can access the admin panel, you must change the name of that directory to something much more difficult to guess."
7.3 Setting directory and file permissions -- Pg 29
For consistency, this title shoudl be "Setting Directory and File Permissions".
The first sentence should start "As mentioned in Section 5.1,"
Last paragraph on the page. N.B. ??
7.4 Removing the installation directory -- Pg 30
For consistency, this title should be "Removing the Installation Directory".
Using "Once installation is completed, you must remove the INSTALL_DIRECTORY?zc_install folder." might keep someone from deleting zc_install prior to installation completion.
Last sentence could read "Until you remove the zc_install directory, a warning message will appear when you access your storefront.
Re: 1.5 Implementation Guide Suggestions
Upon cursory glance, do I correctly gather that all your "for consistency" comments are merely capitalization observations?
Re: 1.5 Implementation Guide Suggestions
Yep, title case for titles except when something like zc_install is in the title.
Re: 1.5 Implementation Guide Suggestions
Thanks for the feedback. We'll incorporate some of the suggestions.
Some appear to simply be differences in expressions or speaking on opposite sides of the Atlantic.
With respect and appreciation for your detailed feedback, I offer the following responses, clarifications, and questions.
Quote:
Originally Posted by
dbltoe
5.1 New Installations--Pg 8
2) configure.php files
Is this really necessary or just a way of confusing those who read this after installing? Numerous posts on the forum are a result of someone renaming the dist- files AFTER installation resulting in a non-working cart. Why not just remove 2) and change 3) to 2).
Yes, it's necessary. You cannot do a fresh install without having configure.php files on the server and setting them writable. Thus step 2 is important.
If someone chooses to follow PRE-installation steps AFTER doing an installation, and wipes out the installation, then ... well ... am I overly insensitive in suggesting that maybe they deserve those consequences?
Quote:
Originally Posted by
dbltoe
6.1.4 Step 3 System Inspection -- Pg 14
Since we are still in the midst of installation instructions, would it not be better to have a warning box (like on page 9) stating:
WARNING: If you see an "Upgrade CFG Files" or "Database Upgrade" button at this point, there is data in the database. Clicking on the "Install" button with either "Upgrade" button showing will erase any data in the database. For instructions on doing upgrades...
I believe there already is the warning you suggest, at the bottom of the screenshot, before the next step.
Quote:
Originally Posted by
dbltoe
6.1.7 Step 6 Store Setup -- Pg 19
When any of these items are described as "used to" are we not falsely indicating that there is no need to enter this information elsewhere? Store Owner Email, Store Country, and Zone are simply insertions of database content, not the creation of a variable that will be "used". Store Address on Pg 19 does not have the "used" statement, but does have a correct version of a used statement in the figure on Pg 20.
I don't think I'm following what you're suggesting. Do I correctly understand that you're suggesting that the assumption people will make is that everything's optional?
Technically it is all optional. There will be undesired consequences if invalid or blank information is supplied, as with any and every setting in any piece of software you ever use.
Thanks for the detailed read and feedback! It's good to know *somebody* reads this stuff! :blush:
Re: 1.5 Implementation Guide Suggestions
:unsure: Take a look at http://tinyurl.com/cdnzbg3. Installed thusly:
- Loaded zip to site
- Apache 2.2.17
- PHP 5.3.6
- MySQL 5.0.67
- Extracted zip to root and renamed folder to zc5
- Created blank database
- Went to MyDomain/zc5 and clicked on option 2 (Run zc_install/index.php via your browser)
- Went through all steps to install
- Used filezilla to rename admin and remove zc_install
- Logged into new admin and changed password
At no time did I create a configure.php file or rename a dist-configure.php file. Both were created by zc_install and the cart file was set to 444. I manually changed the admin to 444 from 644
Thus, the reason I questioned the creation of the files.
Re: 1.5 Implementation Guide Suggestions
Re: 6.1.4
Quote:
Originally Posted by
DrByte
I believe there already is the warning you suggest, at the bottom of the screenshot, before the next step.
Yes, it is in the figure but, I felt a little more emphasis in the subsequent text (including turning it into another orange box) would err on the side of safety.
Re: 6.1.7
Quote:
Originally Posted by
DrByte
I don't think I'm following what you're suggesting. Do I correctly understand that you're suggesting that the assumption people will make is that everything's optional?
Technically it is all optional. There will be undesired consequences if invalid or blank information is supplied, as with any and every setting in any piece of software you ever use.
Under Store Zone, "Again, used for tax and shipping and other related activities."
If this is actually USED for this purpose, one might expect to see the submitted zone (TX) rather than Florida in the Zones Definitions. IMHO it implies that there is no need to go to Locations/Taxes and set it up correctly. Just another item seen a lot in the forums answered by "Did you set your zone?"
If it or Store Country are not accessed in the database in order to perform a function, perhaps it should not be implied that it is "used for". With the exception of Store Name, all the other options state "This is displayed..."
Re: 1.5 Implementation Guide Suggestions
BTW, thanks for the kudos on reading.
I think we'd both agree that there would be far less than the current 177,885 threads if reading were attempted more often.:P
Re: 1.5 Implementation Guide Suggestions
Quote:
Originally Posted by
dbltoe
:unsure: Take a look at
http://tinyurl.com/cdnzbg3. Installed thusly:
- Loaded zip to site
- Apache 2.2.17
- PHP 5.3.6
- MySQL 5.0.67
- Extracted zip to root and renamed folder to zc5
- Created blank database
- Went to MyDomain/zc5 and clicked on option 2 (Run zc_install/index.php via your browser)
- Went through all steps to install
- Used filezilla to rename admin and remove zc_install
- Logged into new admin and changed password
At no time did I create a configure.php file or rename a dist-configure.php file. Both were created by zc_install and the cart file was set to 444. I manually changed the admin to 444 from 644
Thus, the reason I questioned the creation of the files.
Thanks dbltoe, bookmarked this thread for further reference. Replicated your steps on a test site and went just fine - great tip indeed.
Re: 1.5 Implementation Guide Suggestions
Quote:
Originally Posted by
dbltoe
At no time did I create a configure.php file or rename a dist-configure.php file. Both were created by zc_install and the cart file was set to 444. I manually changed the admin to 444 from 644
Thus, the reason I questioned the creation of the files.
You are fortunate that the server on which you are attempting installation apparently has its filesystem configured in such a way that makes that step conveniently simpler. While some might argue it also poses some security concerns, you will certainly enjoy the convenience.
Unfortunately not everyone has that luxury. Hence the reason for the provision and instructions.
As you know, it's tough to find appropriate middle-ground when attempting to accommodate a wide variety of server configurations, each of which is configured according to the whims of the server administrator themselves ... seldom are any two servers exactly the same.
I should also point out that those instructions about creating configure.php files or renaming dist-configure.php files are not in any way "new" to v1.5.
That said, I do appreciate knowing of your personal experience which makes installation easier than what others may experience. Thanks.
Re: 1.5 Implementation Guide Suggestions
Quote:
Originally Posted by
dbltoe
Re: 6.1.7Under Store Zone, "Again, used for tax and shipping and other related activities."
If this is actually USED for this purpose, one might expect to see the submitted zone (TX) rather than Florida in the Zones Definitions. IMHO it implies that there is no need to go to Locations/Taxes and set it up correctly. Just another item seen a lot in the forums answered by "Did you set your zone?"
If it or Store Country are not accessed in the database in order to perform a function, perhaps it should not be implied that it is "used for". With the exception of Store Name, all the other options state "This is displayed..."
Those settings collected by zc_install are the same as those found in Admin->Configuration->My Store.
And, they are indeed used as described.
They were added to zc_install for exactly the reason you mention: because forum questions arose continuously, and the solution was always to redirect them to that section of the admin to fill them in.
Reading between the lines I gather you're suggesting that zc_install also use those settings to preconfigure taxes. I'm sorry, but that won't be happening in zc_install. Tax is way more complicated than that. So is shipping.