Do you write how to's, tutorials or instructions for content managers or clients? Then this article is for you! Find out how Joomla can help you with that, and vice versa: how you can help Joomla.

Saturday August 23, 2025: today I'm going to spend the morning writing my very first Joomla documentation ever. I'm doing this as part of Pizza, Bugs and Fun, a global event to fix bugs and improve Joomla that takes place twice a year. Everybody can participate in PBF events. That is one of the reasons why PBF also includes writing documentation as an activity. Even if fixing bugs or testing pull requests would not be your cup of tea, you can help improve the  documentation and thus help Joomla.

Why documentation matters

Documentation plays an important role in the success of a CMS.

If your user finds your software too hard to use, they'll quit using it. If you find a clear, friendly and logical way to guide them through the features, they'll get comfortable, confident and curious. For that we have Guided Tours in Joomla, and documentation.

Tutorials for different target groups

Joomla's current user documentation needs tutorials that have a systematic structure: in order to learn something about one thing, you first have to learn about another. For example: in order to learn how to edit an article, you first have to understand what an article is, and in order to make an article visible on your site, you have to know something about menu-items. Those simple things are not immediately obvious for new Joomla users. 

Several parts of the user documentation have a different target group, like site builders, technical maintainers of the site, or content providers. Content managers usually don't have to know how to build a Joomla site, how to do the technical maintenance or how to make backups. Roles may coincide, but agencies that build websites often instruct clients how to manage the content of the site, or teach people how to keep the software up-to-date.

Content management tutorials for beginners

Starting with the last Pizza, Bugs and Fun the documentation team first focuses on writing content management tutorials for beginners. So this is what we're going to do today. Herman Peeren, Team Leader of the Documentation Team, has prepared a wish list with topics to cover. He has also opened a Google Meet so we can discuss what needs to be done and how to do it. After a short chat with Herman and Dieter Ziller (who's a member of the Documentation Team), I pick my topic: lists, about adding ordered and unordered lists in your articles. 

Similar to writing instructions for clients

It's not the first time I write documentation: during the ten years I've built websites for clients, I always provided them with extensive how-to's so they could manage their content happily and with confidence. 

Writing these Joomla tutorials is very similar to that, and once I've started writing, I realise how rewarding it already feels to explain the basic features. When you write documentation, you're creating something that is of use for someone else. Somewhere in the world, someone will be able to do something they haven't done before, just because you've written this - even if it's only creating a list in their article.

I also find out that writing documentation / tutorials is not only about describing what to do and how it works, it's also about making decisions. In this case, for example: do we describe multi-level lists? And if so, how far will we go with this? A tutorial doesn't have to be complete; that would be more a reference type of documentation. A tutorial shows something, instead of writing about it.Same goes for my second article, about Intro and fulltext images: do we describe how to use the image class (answer: no, not in a beginner tutorial)? Should there be a little troubleshooting paragraph (answer: yes, because on some occasions, the user might not see the Images and links tab)?

At the end of the morning, I'm happy and proud to tell Herman both my documentation articles are ready to be reviewed!

We can make this work both ways

The beginner content management tutorials are not only great for new users managing their own site; they can also be of use for web design agencies or site administrators. Instead of having to write tutorials for your clients or users over and over again, you could also create a backend module with links to the tutorial articles in Joomla documentation that apply to them. For that to happen, the tutorials need to be complete first. That's where you come in.

If you have to write a tutorial anyway, why not write it for Joomla and then include it in a nice tutorial list module in your backend? 

Go to https://docs-core.sandbox.joomla.org/contributors now, and let's make Joomla the best documented CMS in the world!

Many thanks to Herman Peeren for adding valuable information to this article.