Empowering Joomla! Developers with Knowledge
And a call to arms for veteran Joomla! developers
Written by Andrew Eddie
Given enough time, that "ahha" moment eventually comes. The penny drops. The jigsaw puzzle starts to take shape. I clearly remember when I "got" MVC (Model View Controller) theory and realised my folly at being staunchly opposed to it.
The same can be said for documentation and, in particular, developer documentation. It's a daunting task to work out how to organise hundreds of pages of information just about how you write code to work in Joomla!. We have five types of extensions, three types of applications, all sitting on top of a multi-layer framework involving hundreds of PHP classes and supported by over a dozen third party libraries. Making sense has been a significant challenge that has taken some lateral thinking to solve.
Enter the Wiki - some refuse to use them while others stare in wonder at the organised chaos as if looking at a representation of the Lorenz butterfly. This is one of the tools we are now using to address the enormous task of documenting all aspect of Joomla!. In this article, I want to spend some time going over how we have been structuring our sites to help developers find the information they need.
Introducing developer.joomla.org
Okay, it has been around for a while, but developer.joomla.org is the flagship site that all developers should be aware of, whether you've just entered the playing fields or if you've been about since the Mambo 4.0 days (there are a few of us left - ah, those were the days). This site is progressively being overhauled to give the developer a good cross-section of information as well as supporting our partnering with community projects like Google Summer of Code.
The site is now organised into a few distinct areas:
There are a plethora of blogs that allow our team members and GSOC students to keep you up to date with daily life in the Joomla! developer sphere. It's really worth spending some time soaking these in if you have a spare few minutes in your lunch hour.
There are two main landing pages that are stepping stones to other resources.
The Source Code page gives you an overview of where you can find the various forms of the source code that we produce - from the official release packages, to the nightly builds and if you are really keen, directly from our Subversion repository.
The Documentation Page is the main terminal for your travels into some of the serious developer documentation. This page highlights key areas of the Docs Wiki that you need to be interested in - we’ll touch on this more in a moment.
Finally, the Tutorials and Reviews sections are a recent edition. These are intended to be real meat-and-potatoes articles about things that matter to casual and professional Joomla! developers alike. It's a place for some of the experts of the Joomla! world to brain dump and share hopefully many fractions of their collective experiences.
With that introduction out of the way, let's dig deeply into two other sites that can give you that feeling of vertigo if you stand too close to the edge.
Developer Documentation on docs.joomla.org
The first thing to realise is that information is organised differently on a wiki compared to what you would do on a Joomla! site. The purpose of the wiki is to provide a very low barrier to entry for people that want to help out. However, as I mentioned before, the volume of information is daunting. To overcome this, the coordinators of the site introduced the concept of "personas". That is, they invented characteristics for imaginary people that are seeking information about Joomla!. Now, there are quite a number of these, but the person we are interested in is the Developer Persona. This person has a landing page and this is the gateway to the developer related resources on within the Wiki and also externally, cross-referencing back to the Joomla! developer site where appropriate.
The developer related pages are progressively being placed into categories akin to tagging systems you see on all the social networking sites. For developers, there is one superset and that is the Development Category. This category page will show you all of the development related entries in the wiki. Over time this will grow larger and larger so we have some further subdivisions:
For some of these categories, it is still early days and they are very much works in progress, but you should be able to see all that in the midst of hundreds of randomly placed pages, there is some semblance of ordering beginning to take shape.
Now, here's the catch. The documentation we have on this site is only as good as the contributions from the community, and the good documentation comes from the Joomla! experts. For 1.5, they are still few and far between. So here is my challenge. I'm asking the veterans out there (you know who you are) to help out for a few hours a month to help build up the knowledge pool on 1.5.
Navigating the API on api.joomla.org
There is really now way to get around the fact that API's (Application Programming Interface) are dry as cold toast but they are incredibly useful if you have the right expectations.
The main problem with an API is the fact that they are not a "teaching" resource. They are not like a tutorial that leads you by the hand through concepts and procedures. Rather, an API is a reference for the developer to draw upon when you want to find what you can do with a certain function or class or method.
Joomla!'s API is automatically generated by phpDocumentor (a project I had the pleasure of working with for a short time) and presented at api.joomla.org. The API is divided into quite a number of packages (analogous to how Java organises classes). If you browse the "Select a package" select list you will see a number of packages that relate to third party packages (like PHPMailer).
The main package for the Joomla! API is the Joomla-Framework package. On the page you will see a tree list showing classes and files in this package. It also shows how this package is further broken down into sub-packages. This is one area where you must simply spend time getting familiar for which classes are in what sub-package in order to navigate around. There is a bit of a cheat if you know what class you are looking for. If, for example, you are looking for some information of the methods in the JText class, you can find this in two ways.
If you are familiar with the packages, you will know to drill down into I18N sub-package and then you will find JText in the Classes list.
A slightly easier way is to use a site specific Google search using site:api.joomla.org jtext in the search query. The first result, in this class, is the one you are looking for.
The API is not so good at searching for topics, because it is not designed to be search friendly in that way. Nevertheless, once you work with the API for a while and become more and more familiar with it, the API site can become a valuable reference. If you are lucky enough to have a dual-monitor setup, itis not a bad idea to have the API site open on one screen while developing on the other. On that note, there are development applications that are aware of the API and can give you contextual help within your editor. EasyEclipse for PHP is a good example of this (and it's my IDE of choice).
Even though it can be a bit of a beast, I hope this gives you some insight into what to expect from the API reference and some clues to how it can be coaxed to work for you.
It's in your hands
In closing, I just want to emphasise that documentation for developers is in your hands. We are constantly trying to improve the way information is collected and presented. We now have several sites for you to draw upon as resources of learning about development and applying that knowledge. But the other side of that is that, as I mentioned before, we rely on the whole developer community to pull together and share their knowledge openly and freely. Whether you are fresh into Joomla! or an old-timer from way back, if you would like to help write tutorials or reviews for the Developer site, or need assistance to know how or where to put information on the wiki then please contact me (andrew DOT eddie AT joomla DOT org).
0 Comments