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.

Dieter, your team has an important task! Could you explain to us what the Documentation Team does?

By definition, the Jdocs team is responsible for the creation and maintenance of official Joomla documentation, including translations. This means that in addition to the end user documentation, we are also responsible for the documentation aimed at core developers, extension developers, site administrators and web designers. We are also expected to maintain the help pages, which are available in every Joomla installation, and the API documentation, which is more of a reference list.

So actually you form Joomla's knowledge base. What types of documentation do we have, and does it all fall under your team?

Knowledge base is a big term and Joomla should have a great knowledge base. At the moment we have a wiki for the user documentation with a lot of outdated content, which is also rather chaotically organised, and since mid-2022 a new developer manual (https://manual.joomla.org/docs/), which is an increasingly valuable source of information for the core and extension developers. It is maintained by the CMS maintainers, above all Harald Leithner.

What are the main challenges the team is dealing with at the moment?

Where to start and where to stop? Years of "careless" maintenance will eventually take their toll.

Historically, the wiki was originally intended to cover all topics related to the Joomla CMS. When the wiki was created, the WikiMedia software provided a good basis for a multilingual knowledge base. A large number of volunteers maintained the content. This is no longer the case.

The oldest articles date back to 2008 (if my research is correct) and are still available. The search function cannot filter the age of an article, so you may well be offered an article for a search term that was written for Joomla 2.5. There is no clear concept to allow new users to logically explore the content of the documentation. Furthermore, WikiMedia is still a good piece of software, but it is probably no longer the first choice for our purposes.

So the Joomla wiki is doomed?

The first requests for a replacement platform were made more than two years ago. In addition to other off-the-shelf solutions, a Joomla-based solution is also being discussed. Cliff Ford has developed a component for Joomla and presented his idea in a previous JCM article. He has put a lot of work into making existing wiki articles available for his Joomla based Jdocmanual (https://magazine.joomla.org/all-issues/october/joomla-documentation-a-joomla-solution). This would show all critics that Joomla as a CMS is capable of managing even the largest sites. The benefit to Joomla's image would be enormous if we could say: "Joomla documentation powered by Joomla CMS".

The wiki will survive as Jdocs until a replacement is found. At such time, all relevant existing documents pertaining to Joomla 4 and later will need to be imported.

What does it take to get ahead?

We should form a working group as soon as possible to define the requirements for the next version, prepare a proposal for the board of directors and prepare the application for Google Season of Docs 2025. This is our main task for the next few months. The hanging game - will the wiki stay or not - what comes next - all this has created a lot of uncertainty and needs to be resolved as quickly as possible. If anyone is interested in being part of the working group, please contact me directly on Mattermost as soon as possible.

How do you know what documentation is needed?

Ideally, I am informed by the development team or follow the pull requests to the CMS repo on GitHub. On Mattermost, in addition to the official Docs channel, we have another channel for documentation suggestions and finally the Documentation Buddies channel, the purpose of which Phil described in more detail in his JCM article (https://magazine.joomla.org/all-issues/november-2022/document-buddies-making-joomla-better-without-writing-a-line-of-code).

How does the team work? Do you have meetings? A Mattermost channel? Tools you work with?

Team members work largely independently and at their own discretion. At the moment, there are so few active members that it is sufficient to share information via the Mattermost channel (search for PD Documentation in Joomla’s Mattermost instance). If we can attract more contributors, I can imagine regular video meetings again. A docs sprint might also be necessary if this is the only way to get a better result from the planned working group. At the moment we are just using the tools we have, such as the internal wiki tools and what GitHub and Google provide. But I am open to new suggestions.

I understand you're looking for volunteers. What kind of people are you looking for? Can anyone join or do you need to be super tech?

I could say that we take anyone who is willing to help - but that would only be half the truth. Some experience with Joomla is helpful, but not essential. After all, we also want to make the user documentation usable for newbies. It is difficult for experienced users or programmers to put themselves in the position of a newcomer. They often forget to mention the intermediate steps that the experienced user needs to master and that drive the first-time user to despair. What seems more important to me is the desire and enthusiasm to write. I hope that this statement will encourage some potential new authors or translators to get in touch with the JDocs team on Mattermost.

What is expected of a team member?

Empathy and a sincere desire to help. Joomla is used all over the world. We offer our CMS to a wide diversity of people with a wide range of experiences. Respect for the recipients of our documentation must be our first priority. This must be reflected in every sentence of the documentation.

What is the most common misconception about Joomla documentation?

I myself fell victim to a misunderstanding at the beginning: I also wondered if my very limited knowledge was enough to understand how the PHP code, SQL database and CSS instructions come together to form an HTML page and display pages that are both informative and visually appealing. Would I be able to compete with people who know how to juggle code snippets day after day in a way that looks like magic to outsiders?

However, user documentation is written for people who want to learn something, not for people who know something. And it should be written in a language that the reader understands.

This means that you don't have to be a super programmer (which can sometimes be a disadvantage) to write a tutorial or manual.

So folks, even if you don't know how to code, don't be afraid to contact Joomla. Have a look at the Volunteers Portal under "Help Wanted" to see what tasks you're interested in, and don't be afraid to contact the team leader. Volunteers are not only needed for documentation. I am sure the Marketing, Social Media and Website teams would also welcome anyone willing and able to help.

If I don't have time to contribute regularly, can I help out occasionally, for example during a PBF event?

Nobody expects a certain number of pages to be created, or at least x hours per day/week/month. If a user happens to spot a typo or other error and corrects it, or reports the issue due to lack of time or knowledge, then that is just as valuable to me as writing a whole page. The PBF event is an opportunity to meet new people in a friendly environment, in person or virtually. There are so many users on the floor that it's very easy to try out new things because you can get help with questions right next door.

Can we help in any other way?

As already mentioned, our wiki runs on the Mediawiki software. Recently, due to a fluctuation of volunteers, the situation has arisen that no one in the team has much experience of administering the Mediawiki server, or is always available for work or private reasons. We are therefore urgently looking for someone who has experience with a large Mediawiki installation and can assist our administrator.

Is there anything else that is close to your heart?

I should be happy about this - but the current situation is frustrating. We have an increasing number of registrations on Jdocs. In the last 12 months alone, over 900 people have created new accounts. No doubt, there are some who have created a fake account.

We have the problem that due to a lack of maintenance of the scripts and control of the Wikimedia extensions, the process that should run next is broken. I can currently see that user XYZ has registered. However, I cannot contact this user until they have confirmed their email address. The user list also shows whether the new user has already created their own profile page. This can be a short line that can be created quickly.

As I have to go through the list by hand, this would help me a lot to welcome new helpers and support them if necessary.

So if anyone has missed a response from us after registering, please contact me via the Volunteers Portal!