For the first time since getting involved with Joomla I’m actually excited about the state of Joomla documentation for extension developers!

In the past Joomla hasn’t had the best reputation for developer documentation, but for me the Joomla Manual is a big step forward. I think it’s important for the Joomla project to view extension developers as “customers” and make it easy for them to find all the good stuff that there is in Joomla.

I joined the small team contributing to the manual about a year ago, and it’s been very satisfying to see the Manual taking shape. We’re not there yet, but definitely on the right track.

Who is it for?

It’s primarily a resource for developers of Joomla extensions. You'll find it here: https://manual.joomla.org/. 

For those just starting out in Joomla development there are Getting Started pages, with details of how to get your development environment set up, as well as how to make contact with other Joomlers, and where to get help when stuck.

Within Build Extensions we've a new Module Tutorial which takes first-time developers step by step through the process of developing a Joomla extension, while introducing some key Joomla concepts along the way.

For developers considering upgrading their extensions to align with the new principles introduced in Joomla 4, there's lots of material in General Concepts covering topics such as Namespacing, the Web Asset Manager, Dependency Injection and more.

And for those who like to keep a close eye on what's coming in the future, the Migrations section contains details of all the new features and deprecations on a per release basis.

What's so special about it?

In a nutshell, it's all geared around making it easy for developers.

For the first time, we now have all the developer documentation in one place, easily navigable via the explorer pane on the left. And via the version dropdown you can find documentation which is specific to a particular version.

The manual is built using Docusaurus, which not only has a really nice presentation, but also checks for consistency - for example, ensuring that there are no broken links. You write the documentation using markdown syntax, with some additional Docusaurus extensions.

I particularly like the ability to upload and store zip files there. I often felt frustrated when documentation included a section of code, but I didn't understand how to fit it into an overall extension. So there are plenty of sample components, modules and plugins which readers can download and install, and can use as a basis for experimentation.

There's also a sister github repository https://github.com/joomla/manual-examples where we’ve started storing some of the sample extensions. For example, there's an “example form” component which presents the HTML form generated from a form XML file, and displays the raw and filtered/validated data submitted. So readers can use this as a basis of investigating other Joomla standard form fields - just plug them into the XML file - as well as adapting to their own requirements the provided custom field, filter and validation rule.

Want to help?

Although the Manual is in a fairly good state overall, there are certainly areas where contributions would be very useful. Up until now a lot of the focus has been in getting the newer aspects of Joomla 4 and 5 documented, as that was a significant gap that needed addressed.

Now we're in the process of converting the remainder of the Joomla 3 documentation to include it as well. Mostly this involves minor amendments to take account of version 4/5 changes, plus modifying the text to use markdown syntax.

If you're keen to contribute as part of August Pizza, Bugs and Fun, then why not put yourself down to convert one of the existing document pages. They're mostly under

• the Joomla API Guides and
• detail pages for the various types of plugin events

All the details for how to go about it are within the README at https://github.com/joomla/Manual - this repository is what the Joomla Manual is built from.

We're also very light on Accessibility. If you're knowledgeable in that area then contributions would be most welcome!

On a personal note

I’ve found that collaborating with others on producing the Manual has provided much more of a sense of teamwork than when I was producing Joomla 3 documentation. My thanks in particular go to Harald for his patience and guidance, and to Fedir who has always been ready to help with his technical expertise.

Conclusion

I googled “we’re getting there” to check that a definition of this English idiom was readily available, and found an interesting 1980’s promotional video of British Rail (the GB national rail company), whose slogan at the time was “We’re Getting There”. Unfortunately it was shortly after this that the company was split up and sections of it privatised! However, I’m sure the Joomla Manual has a lot more promising future ahead!