The Joomla! Forum™

This is a critique of the installation portion of the Joomla! User Manual 1.0x http://help.joomla.org/images/User_manu ... mbined.pdf. It also touches on aspects of the browser-based Joomla! Installer http://help.joomla.org/content/view/39/165/ and the Manual Installation http://help.joomla.org/content/view/40/132/.

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.

Overview

• 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.

Here are more specifics:

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.

Joomla! Installer Problems

• 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.

Manual Install Problems

• 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?

It is the job of the Joomla! Installer program to make the user's install experience pleasant. The User Manual should provide clear and complete coverage of the installation process. I understand that this is a volunteer effort. While I appreciate the work that went into getting the documentation to this point, I feel it has some ways to go to reach a stage where it is truly effective.

-Ken

Ken,

Thank you for your suggestions!  Up untill now, the User manual has been mostly written by one volunteer who is currently unavailable. 

It is my hopes that one day we'll have a small team just to tackle completeing the User Manual.  Right now with our limited volunteer hours, we are putting our efforts on the Help Screens.

Chicken/egg conundrum.  For volunteers with technical writing skills to be able to join a team explaining Joomla! to others, they have to first learn the system.  Since there isn't documentation to help us learn, we can't help write the documentation.

I agree, but there are things beginners who can write are ideally suited to do. One of those is point out problems with the install documentation. Here, Joomla! veterans are sometimes at a disadvantage: they are so familiar with the system that they can overlook writing down certain critical steps they unconsciously take when installing.

So, I took the time to put up these posts both as a help to the documentation team, and as notes to myself if I find time to contribute.

Anyway, once a critical mass of quality documentation is achieved, I think the Chicken/egg problem will be greatly reduced.

-Ken

For volunteers with technical writing skills to be able to join a team explaining Joomla! to others, they have to first learn the system.

Those with technical writing skills even if they are not greatly familiar with Joomla! can help in the way of proof-reading.