Every once in a while we get a unique project – a project that requires us to dig into every hidden feature in Joomla to know how we can execute it the “clean” way, without making core modifications and without creating tons and tons of code that could’ve been saved if we just used one of Joomla’s not-so-well-documented built-in classes. Sometimes – this process takes a full day – and it’s all because Joomla is not properly documented…
There are many hidden features in Joomla – too many to be called “Easter Eggs” – that can be helpful in the implementation of challenging Joomla projects. Unfortunately, these hidden features are so hidden they are not even documented – not even on Joomla’s official site. If you’re not convinced, then do a small search on Google on “how to cache a custom Joomla module”… We’re sure that it’ll take you at least an hour to find out how – and that’s because this feature that is extremely used by Joomla developers is not documented at all. (In case you really want to know how, then you will need to create a field named cache in the module’s manifest [XML] file. The cache field should be of type list and it should have a value of 0 [no caching] or 1 [use global configuration]).
The examples supporting our point are countless. For instance: how can you allow the user to change the layout of a custom Joomla module, how can you find a Joomla article by ID, etc…
Another problem with the documentation is that it seems that its momentum has been lost since Joomla 1.5. That’s why you see many Joomla features documented in Joomla 1.5 instead of Joomla 2.5. Some features even have “Joomla 1.5 screenshots that also apply to Joomla 2.5”. We don’t like to be judgmental, but we think this is lame!
It’s lame because it gives Joomla developers (and administrators) the impression that Joomla is no longer properly maintained – it is no longer properly cared for – which means, at one point, it will wither and die. We all know that this is not the case: Joomla is probably the most maintained CMS (from a technical perspective) on the planet! But everyone judges a book by its cover – and documentation is the cover!
Another issue with the documentation is that it’s not organized and it’s not intuitive to browse. One would expect to have every functionality described for every type of extension (for example, the Custom HTML module) from the outside (if the person is a normal user) and from the inside (if the person is a developer looking to extend its functionality) – but this is not the case. Instead, the homepage of Joomla’s documentation is a messed page that is highly confusing. Also, clicking anywhere would certainly lead somewhere else that has a high density of red links (e.g. links that are not linked anywhere – or “suggested topics”).
The final, and most important issue we notice in Joomla’s documentation is the questionable accuracy. Some guides are written by experts (we know that for a fact), while some other guides are written by Joomla enthusiasts that have started using Joomla for a year or two and think they possess the sufficient knowledge to write guides about it. Such guides are typically badly written (we’re talking about really bad usage of English grammar here), inaccurate, don’t make full use of Joomla’s power, and, in most cases, will only work under certain conditions. What makes things worse is that one cannot comment on these guides and warn others, which means that everyone reading these erroneous guides will fall in the same trap. Not good!
So, what’s the solution?
Well, we think that Joomla needs to implement the following substantial changes in its documentation:
- Allow for moderated commenting on Joomla’s guides – especially on those guides written by enthusiasts. The PHP website is a great example that must be followed.
-
Review (moving forward) all guides submitted to Joomla for accuracy.
-
Make the search feature (on the documentation portal) fuzzy. In other words, if we search for “How to create a user in Joomla using PHP?” we get a relevant result. This is a very ambitious feature but it can be done.
-
Allow 3rd party companies to easily contribute to Joomla’s documentation. These 3rd party companies (that include us) want to see a thriving, prosperous Joomla and will do anything to keep it that way!
-
Get some UX experts to ensure a smooth navigation on the documentation portal.
-
Ensure that the documentation is always up-to-date.
OK – we know that what we’re proposing is a bit ambitious, but it’s necessary to the long term survivability of Joomla. If things are left the way they are right now for a couple of years, then we’ll end up with a completely inconsistent, incoherent, and wrong documentation and then people will really start migrating from Joomla to other Content Management Systems (the alternatives are not that great at the moment by the way, but nobody knows what can happen in a few years).
Yes – this post is a bit on the harsh side – but someone had to write something about this. The frustration that the documentation is causing to anyone using Joomla (whether an administrator, a designer, or a developer) is growing by the day. This needs to be stopped…
Now, if you want to implement something in Joomla but you can’t find the necessary documentation to do that, then please contact us. We’ll do it for you in no time, we’ll explain to you how we did it, and we won’t charge you much.