Community Magazine

In this tutorial you can learn how to make a tutorial.

A tutorial is a lesson that takes you by the hand through a series of practical steps. It offers a learning experience by doing something. It is the best way to get to know a subject you are not yet familiar with.

Diátaxis is a methodology to improve documentation by dividing it into four categories, serving different needs. We are going to use this approach to improve the documentation of Joomla, but you can also use it to document your own extension or write user manuals for your clients.

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

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.

A wise person once said: “The quality of software is measured by the quality of its documentation”. OK I just made this up, but it could very well be said by a wise person, because it makes sense. Where does Joomla stand, documentation-wise? And how can you help Joomla to get the documentation it deserves? We asked Dieter Ziller, Team Leader of Joomla's Documentation Team.

Joomla documentation is plentiful and easy for anyone to contribute to. Over the years the Joomla Documentation Wiki has grown considerably, which in itself is good, but also brings challenges.

In the last magazine article: Guiding you through Guided Tours, we looked at guided tours (available in Joomla 4.3) and walked through their use. We stopped at the point of creating a guided tour as an administrator and as a developer.
Now we will finish that journey so you can build your own!

Whenever Joomla gets picked as a Google Summer of Code (GSoC) candidate there is a flurry of activity around several projects. In 2022 one of the projects put forward was Guided Tours. This is a project that has been tackled by several students over several years and each one has nudged closer to the finishing line, but never quite got there. That's why it's especially gratifying to see Guided Tours as the main feature of the Joomla 4.3 release. It's the culmination of a lot of teamwork and a great example of what can be achieved if you just keep at it.

Many things are attributed to Albert Einstein which probably never left his mouth, but one that seems to stick is:

If you can't explain it simply, you don't understand it well enough.

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!