Get the Documentation Back on Track

What is the current state of Joomla’s documentation? What’s new and different? What are the future plans? How can you help?

The "old" documentation

Joomla’s official documentation can be found on docs.joomla.org. It is a system based on MediaWiki. Basic idea is: everybody can easily contribute. It also has built-in provisions for translations. In the course of time  the structure of our documentation deteriorated and it became increasingly difficult to find anything. The system went off the rails. 

Alternatives for MediaWiki

Some years ago some Joomlers looked for an alternative for MediaWiki. They came to the conclusion that Github would be a good base to store the documentation, because of its version control. The new documentation would be stored in Github markdown format, which is more general than the custom wikitext markup.

Two types of implementation were explored that both use markdown pages in Github:

• built with Docusaurus, an open source Node/Typescript project from Meta/Facebook ¹. Updates of the content via pull requests. Translation can be done via Crowdin, Joomla’s official Translation Partner, that is also used to manage the language packs. It was built and is maintained by Harald Leithner. Three parts of the documentation are now running with Docusaurus:
  
  • • The developers manual at manual.joomla.org. Priority there is to get that complete and up-to-date. It is growing. Translation might be considered after completion, but is left out for now.
    • A prototype of the “user manual”  on docs-next.joomla.org.
    • Internal documentation for Joomla's project management.
• built with Joomla, using a custom component: JDocManual. Built by Cliff Ford. See repo at github.com/ceford/cefjdemos-com-jdm. Management of the content can be done in Joomla and language associations are also the Joomla way. ² But the Joomla project has bad experience maintaining custom components (like com_jed).

Although some years ago a conclusion was that Github markdown is the best option, we are now also (again) investigating a “core only” Joomla solution. A prototype is being built.

Until now the Help Pages (you see them when clicking on the Help-button in the Administrator-side) were also part of docs.joomla.org, but there are plans to put them apart in another system. 

The reference in api.joomla.org is automatically generated from the docblocks in the code by PhpDocumentor. That doesn’t have to be changed,  we only need some maintenance to keep everything up to date with Joomla and PHP.

Thank you, Dieter!

From August 2023 the PD Documentation Team was led by Dieter Ziller, who has put a lot of energy into moving forward with the documentation ³. He was the captain on a stormy sea; there are different opinions on how to proceed. And although good documentation is crucial for the future of Joomla, spending time on the documentation is not the favourite activity of most people. It is difficult to get enough volunteers.

On behalf of the whole community, I want to thank Dieter for his efforts as team lead! Fortunately he will keep contributing on the much needed improvement of our documentation.

Who the heck is Herman?

At the end of October Herman Peeren, that's me 😅, took over from Dieter as team lead. 

I’ll introduce myself: I’m a developer. While studying something completely different, my first job as a programmer was in 1977, still with punch cards back then, no internet. Yes kids, times have changed 😂. Later I studied Computer Science. I love the creative side of modelling and coding. For 25 years I mainly earned a living as a theatre performer. In those years my programming projects were for controlling light and sound, and for administrative purposes. When the internet became available for everybody, about 1995 in the Netherlands, we started making websites. For programming backends I hopped on the ASP.NET bandwagon at the start of the millennium. I made some small CMSs myself and later switched to DotNetNuke (now called DNN), an open source CMS/platform on the .NET stack. 

I only looked at PHP from version 5.3 onwards,  when it became object oriented. My first PHP-project was another self-built small CMS, using the exotic Delphi4PHP (a disaster with inline styles). About 2009 I started looking at Joomla. Made templates with Flash (whose Ecmascript based Actionscript was ahead of its time), explored Nooku as a framework for Joomla and used Doctrine ORM for better handling of entities and relationships. I mainly made custom intranet-applications for very different businesses, like a Management Information System for online flexwork agencies and a planning system for hot air balloons.

Besides Joomla I was active in several communities, like Delphi in the Netherlands, Domain Driven Design (DDD) and the last years: Model Driven Engineering (MDE, making Domain Specific Languages). I like to be part of a community. Joomla is my main “family”.

In short: I know quite a bit about development, love modelling, coding, and to be part of Joomla, but I don’t know much yet about documentation (working on that).

Cutting the knot this year

The last few years a lot of energy has been put into the alternatives for our MediaWiki based documentation. That was necessary, but the content and structure of our documentation got less attention than it needed. Progress was mainly made with the developers documentation on manual.joomla.org, but if new users are coming to docs.joomla.org, they get lost in a mess of obsolete information. That is disastrous, as it blocks newcomers, while we need them to keep Joomla alive.

So my goal is to reach consensus about how to proceed before the end of the year. Especially for the “user documentation”. The coming time we’ll thoroughly compare our four options:

• Put MediaWiki up again, but then well structured and searchable, with guarantees for maintenance in the future.
• Use Docusaurus and work out a workflow for contributions and translations that is easy to use.
• Use Joomla with a reliable 3rd party component. This would be comparable with JDocManual, but not maintained by the Joomla project itself (still being investigated).
• Use a “core only” Joomla solution. Would be a nice showcase of Joomla’s capabilities, but we are still investigating all pros and cons.

Besides comparing the different solutions in which the documentation will be implemented we are also setting up a good structure for the content of the documentation. We will try to finish both before the end of this year, so we can go full speed ahead next year.

2025: year of the documentation

I’ve set the goal for myself to have a good, accessible, useful, complete and searchable  documentation ready by October 2025, when Joomla 6 will be released. The documentation for site builders, site maintainers and content maintainers should be attractive for new users. Docs.joomla.org must be a reliable source of actual information, either by providing that information or by referring to the correct information elsewhere.

Our plan is to organise some “documentation sprints”, comparable with a Pizza, Bugs & Fun meeting, but then totally focussed on documentation ⁴.

Teamwork: we need you!

Notes

1. Developer manual, also see (August 2024): https://magazine.joomla.org/all-issues/august-2024/joomla-manual-we-re-getting-there and the Docusaurus-meeting from August 2022: https://magazine.joomla.org/all-issues/august-2022/docusaurus-to-the-rescue-for-developers 
   
2. JDocManual, also see (October 2023): https://magazine.joomla.org/all-issues/october/joomla-documentation-a-joomla-solution 
   
3. Also see this interview with Dieter about the documentation team (August 2024): https://magazine.joomla.org/all-issues/august-2024/documentation-a-great-way-to-contribute-to-joomla 
   
4. Here is another initiative we might revive to boost the documentation: Document Buddies (November 2022): https://magazine.joomla.org/all-issues/november-2022/document-buddies-making-joomla-better-without-writing-a-line-of-code