I recently installed Joomla!, first trying the "easy browser install", and failing, and then moving to the "less-easy manual install", and eventually succeeding. In all, the whole effort took me over 20 hours. A lot of that turned out to be not the fault of the Joomla! install process, but a fair portion of that time was consumed by out-of-date, misleading, and incomplete documentation.
- The biggest problem with the Installation portion of the User Manual is that it is a 'happy path' document. If everything goes perfectly, you barely need to read the installation portion. But if anything goes wrong, the document offers no help. A quick look at the Installation section of this forum shows lots of lost, desperate users with broken installs trying to get answers.
- I think this User Manual has a misguided sense of 'user-friendliness': all too often, the User Manual over-simplifies critical details, doesn't explain all options, or fails to follow convention. This missing information inevitably makes the user's work harder, forcing them to guess rather than make informed decisions.
- One of the principles of writing how-to documents is giving the reader just enough information required to complete the next step. The User Manual has problems in this area, too. In particular, the prerequisites are badly handled. It requires the user to manually gather information that will be provided automatically at a later step, and also neglects to list requirements for certain information that the user definitely will need to know to have a successful install.
User Manual Problems
- Simplify System Requirements. Say only that "Joomla! requires Apache configured with PHP and MySQL." The Installer program should be responsible for showing the current requirement details. If you want to repeat them in the document, put them in an appendix.
- Add requirements for all the information the Joomla! Installer will ask the user, especially the MySQL host, username and password. The MySQL information is very misleadingly explained in the current document.
- The User Manual should concentrate on getting the user to the first Joomla! Installer screen. Putting screen shots of the Installer in the manual is just a waste of effort: they are already out-of-date. Remove them.
- Obey convention. If the default install directory is joomla, suggest that to the user. Don't use "Joomla!_folder", as it is now, because that folder name will cause Linux installations to fail.
- Move the bulk of the installation documentation to the Joomla! Installer program itself. Because it is much more likely to be current, the Installer should contain the up-to-the-second requirements, instructions, and troubleshooting messages.
- Offer links to help resources.
- Auto detect more of the System Requirements. The apache_get_version ( ) and mysql_get_server_info () php functions let you automatically retrieve everything you were asking the user to get manually.
- When Directory and File permissions are incorrect, much more specific instructions need to be given on how to set them properly. The procedure in the Manual Install section works well, and should be adapted.
- Add the 'unhappy path' instructions here. Troubleshooting screens and help resources could be displayed when System Requirements aren't met or errors occur.
- Rewrite the Step 1 MySQL database configuration screen instructions. It requires an existing MySQL user, with superuser rights, and the corresponding password. Say it. Why have two columns of confusing instructions? Have one column of clearer instructions.
- Bring this page up to date. This problem has been going on since November of last year (see http://forum.joomla.org/index.php/topic,37696.0.html )
- Provide usable sql scripts. The ones in the tarball have been modified for automatic installation. Include the admin creation script. (See http://forum.joomla.org/index.php/topic ... l#msg63069)
- I never could get the tar command to work. Is this a shell/version of Linux problem?