In a hotel conference room in Darmstadt, Germany, a small team of Joomla enthusiasts got to grips with Docusaurus, taming the beast to the advantage of the Joomla developer community. This neat package of software is probably the most important change in Joomla documentation for a long time, and with the added bonus of slaying the dreaded MediaWiki captcha once and for all!
The team that assembled on 24 July 2022 in Darmstadt, Germany, were:
Benjamin Trenkle (DC Production), Philip Walton (DC Outreach), Mike Brandner (TL JDocs Team), Christiane Maier-Stadtherr (TL Joomla Accessibility Team), Viviana Menzel (TL Accessibility Team) and via online Shivam Rajput (TL Enhancement Development Team and Google Summer of Code Joomla Team) and also online Harald Leithner (DC Operations).
The meeting had several key objectives:
- Find clarity in the future of JDocs,
- Prepare for the application to the Google Season of Docs
- Understand the new software for Developer Documentation and make it operational.
Planned projects for the GSoD
The planned projects for the GSoD were presented and discussed.
Documentation for developers was the first project. There was an attempt to solve this earlier in the year, but it was not continued. We needed a solution.
Harald presented Docusaurus 2, an open source tool from Meta, which is available on GitHub and supports versioned documentation.
The general consensus was that this is a very good tool to start the documentation of new features.
GitHub: https://docusaurus.io/
The second project was user-friendly documentation for Joomla! Users, the “Joomla User Guide”. There has been a lot of feedback from Joomler users. Many find the current JDocs too complicated to use, there is quite a high entry level so it's not conducive to being self-taught. Suitable documentation from external sources that give the right answers is also hard to find.
For this second project we decided to create a stand-alone website as a source of user-friendly documentation. This does not have to mean the end of the JDocs with MediaWiki, just another website that contains something like the user manual of Joomla. Clearly structured and only with contents for the supported versions.
For both projects, the JDoc page for GSoD 2023 was created and filled with initial information: https://docs.joomla.org/GSoD_2023
The idea is to get a grant from GSoD to fund technical writers. They will then push the project forward, supported by the mentors of the projects. Too often, the momentum has run out, so this approach will hopefully bridge the gap between need and reality that so often evades us.
The main workshop
In the following workshop, the new Joomla! Developer documentation was explained, and all those in the room started setting it up together. Benjamin helped with technical issues, but the system is straightforward. The initial structure was created; see: https://github.com/joomla/Manual
A great feature is that the documentation is written in markup and managed through GitHub, which is much more intuitive than MediaWiki (from a developer's point of view).
In order to keep the developer documentation up to date, it is also planned to require a Dev Docs entry for every feature PR from Joomla 4.3 onwards, before it can be merged. Lack of good documentation has been the curse of so many software projects, and Joomla has been no exception. To tackle this, we need to take documentation as seriously as the code it documents.
Plans for the Project “Joomla User Guide” were discussed. There are no concrete plans for the platform that will be used yet, and we are open to suggestions. One idea was to use Joomla as the platform; perhaps there is a better-suited tool, and we welcome feedback.
The handling of the translations could be managed via Crowdin, so we already have an established system for managing this.
Towards the end of the event, the discussion turned to where the Joomla documentation should go. In our discussions, it became clear that the existing JDocs should be maintained and operated as a documentation platform for the community. The help pages are already set up, so we cannot change too much, although there could be plans to automate some of that process.
What is desperately needed is documentation that users can use to find their way around easily. This is the path we would like to take with the "Joomla User Guide".
Your part in the plan
This will involve a lot of work, for which we will need many contributors, so please do consider giving some of your time. If you have ever suffered from a lack of documentation, then now is the ideal time to come forward and help fix that issue, so others do not have the same problem.
If you would like to support the project, please feel free to contact the JDocs team or send a direct message via Glip or email to
