One of the common frustrations with open source projects is a lack of dicumentation. Coders love to write code (me included). For a coder, it is often a big task just to add sufficient comments to their computer code. Producing good documentation on how to use the program is yet another level of task. And one of the cool apsects of open source programs is that they can change and improve quickly - which is not so cool for those writing documentation.

While building this website, I encountered a documentation problem in Joomla!, the open source content management system that I'm using. Here, however, it seems that information needs to flow in the opposite direction: from the documentation folks back to the coders. A configuration variable called $live_site is known to the documetation folks to be important, but the coders seem to consider it optional and make it hidden to most users.

Documentation

I am the only user for most of my computer code. Still, I find I have to document it pretty carefully for it to be useful. The point is that I do many different projects, and I will often come back to modify some code years after it was originally written. There is no way I'm going to remember what I was thinking when I wrote some piece of code last month, let alone last year. My programming rule is that a good documentation must be written first and foremost for myself, and particularly a version of myself who has suffered significant amnesia.

I mention this to note that I truly feel for the writers of documentation. It is a difficult job to make things clear, and even more complex when you need to keep up with a fast changing open source project.

Nevertheless, when you hit a snag from the user perspective, it gets really frustrating and you just want to vent. The documentation folks are the easiest target. "Why couldn' t you just have included this crucial piece of information in the first place?" is probably a cry common to support forums. In my case, that would be shooting the messenger instead of the real source of the problem.

Joomla!

I'm using Joomla! (the exclamation point is part of the name, but rather annoying) as a content management system (CMS). It is pretty easy to use, with a graphical administration interface and lots of nice features. It is the first CMS that I've used, so I can't compare it in detail to others. What helped me try it is that there is a rather large community built around it, both open and commercial.

Joomla is built upon PHP and MySQL. One result of this is that the URLs for most pages look something like

http://example.com/index.php?option=com_content&view=section&id=4&Itemid=37

All the stuff after the "index.php?" are the parameters needed to make a database query to retrieve the content. Besides looking a bit strange to most folks, I'm told that search engines don't index such pages all that well.

The basic solution is that Joomla has an option to re-write these ungainly URLs to be user-friendly and, more importantly, search engine friendly (the SEF URLs in the title of this post). This is just window dressing, of course. Behind the scenes, PHP and MySQL still need the same parameters for making queries. Joomla just provides a translation layer. The ugly URL above becomes easier for humans (and search engines) to read:

http://example.com/index.php/more-about-joomla

Isn't that prettier?

In Joomla's graphical admin interface, there is a simple checkbox for using SEF URLs. However, for my site, enabling that option made most of my site's pages unaccessable. The dreaded "404" errors popped up for everything but the few highest level pages. Since these were mostly navigational pages, the real content could not be accessed with SEF URLs.

I checked the standard documentation. Yup, I did everything right. I fiddled with all the GUI configuration options. No luck. I played with mod_rewrite and .htaccess and things got worse (code 500 - internal server error). I checked my hosting provider's FAQ and got sent down a blind alley for a while. These are the usual steps in problem hunting, and they are never fun.

After significant effort and no solution, this problem really bothered me. I investigated switching to Drupal (another open source CMS).

Click-n-Cripple

Now, I could have lived with the standard URLs. I saw several comments that said that good content is the only measure of a web site, and that SEF URLs don't make that much of  difference. True, google coders probably know a thing or two about doing URL translations themselves. Why worry?

Part of it is because I wanted to test Joomla. If the software couldn't provide one of the standard features it advertises, then why should I expect it to be reliable on more advanced features? The other part is that I want to be able to understand my own URLs. If I have to remember section numbers and category codes just to give someone a link, I'd go crazy.

The solution came via my hosting provider and their automatic, and useless, Joomla intallation. I'm using 1and1.com for shared Linux hosting. They offer something called "Click-n-Build" to install a variety of applications. Joomla is one of those applications, and I originally wasted several days trying to build a web site with their automatic Joomla installation.

The crucial point that 1and1 doesn't tell you is that the installation does not give you write access to the Joomla directories. Hence, among other things, you can not change the Joomla template. That means you cannot change the logo at the top of the page. Their "Click-n-Cripple" install of Joomla is only suitable for building a site with Joomla advertising all over the page. No thanks.

Hidden Variables

One thing I remembered from that massive annoyance ws that SEF URLs worked. So I reinstalled a crippled Joomla to see what was different compared to my own installation. Hidden in the configuration.php file was a variable called $live_site that was filled in for the cripple, but not on mine.

There is no GUI option for the $live_site variable. I checked the documentation and it said that $live_site is optional. Great, but how can it be optional when there is no way to set it? Well, of course you can set it. You just have to edit the configuration file by hand. Not what one expects from a system that touts its GUI. And, by the way, the configuration file is set by Joomla to be read only. You have to change permissions, edit, and change permissions back.

As you no doubt have guessed, the live_site variable fixed things. Wow, that was a whole lot ofnnoyance for one little setting change. Somebody should add this to the documentation. Of course, now that I knew what I was looking for, I found it in the documentation:

http://docs.joomla.org/Why_does_my_site_get_messed_up_when_I_turn_on_SEF_(Search_Engine_Friendly_URLs)%3F

Gads. Why couldn' t you just have included this crucial piece of information in the first place?

My true complaint is not with the documentation. Yes, this would be good to put in a place that is more easily found. But the true problem is that Joomla has a GUI-based administration. The GUI programmers chose not to include an "optional" variable among the administration options. Had it been there, I would have looked it up and like found the above page. I certainly would have tried filling it in vs leaving it empty.

Joomla programmers, read your documentation every now and then. The documentation folks have learned things about how your software works in the real world. Great code, but this small omission had me reading the Drupal install guide for a while.

OK. Problem solved. Frustrations vented. Time to move forward building the site. After all, I do think that good content rules all on the web.