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.

Documentation is crucial for Joomla: it is the main entrance for new users and it is necessary to conveniently use all possibilities. An improved documentation can attract more users to Joomla and help them to happily keep using it. 

Different needs better served

Documentation is used in different ways. For instance: 

• To learn some basics and get familiar with a topic.
• To get something specific done.
• To look up the possible settings and definitions.
• Or to deepen your understanding.

Each of these cases need a different form of documentation. When looking up what some used terms mean, you don’t want to go through a large step-by-step tutorial. On the other hand, when new to (a part of) Joomla, you don’t want to be thrown in at the deep end right away.

The four different uses of the documentation listed above are the result of a division of user needs over two dimensions: 

• Practical steps (action) versus theoretical knowledge (cognition).
• Serving study (acquisition) versus getting work done (application).

You can learn things by doing, like learning how to ride a bicycle or how to swim. Or you can learn by reading a description of the structure or the theoretical background. This is action versus cognition.

You can study something or accomplish some practical goals, getting work done. This is acquisition versus application.

This gives us four kinds of documentation that are targeted at best fulfilling the four different user needs:

• A tutorial is a lesson that takes the student by the hand through a series of practical steps to realise a project. It serves the need to learn about a topic.
• A how-to guide is a recipe that takes the already-competent user through the steps required to complete a specific task.
• A reference provides a technical description of the machinery. It is information oriented.
• An explanation illuminates and clarifies a particular topic, discursively. It serves the need to understand.

This is the basis of the Diátaxis framework, a methodology that has successfully been used to improve the documentation of several other open source projects, like Python,  Django, Django CMS, Wagtail (Python/Django CMS), and Ubuntu Core. 

A compass to find the direction

Documentation improves by making a conscious distinction between those four types. Merging those types makes the documentation less clear: it takes new users a longer time to find their way and it takes experienced users longer to find specific information. It doesn’t necessarily mean that the whole documentation must be divided into four parts, but it helps during the writing process to be aware of what category an item belongs to. 

A way to gradually improve existing documentation is to analyse each item, individual paragraphs or even single sentences as to what needs they serve. This is done by asking two questions:

• Is this practical or theoretical? (upper or lower part of diagram)
• Does it serve study or work? (left or right part of diagram)

It needs a bit of training to do this analysis correctly, but when using this compass you can determine which category something belongs to more accurately than just intuitively making the distinction. And by separating those parts they can be used more effectively.

Tutorials and how-to guides are often confused. A tutorial is an introduction. The product of a tutorial is less important than the process of doing it and what you learn from that. Whereas a how-to guide is a recipe to accomplish a specific goal. Don’t be fooled when the title of a tutorial contains the words “how to”. 

Joomla’s Guided Tours: How-to guides

Since Joomla 4.3 we have some special tutorials and how-to guides targeted at Joomla users: Guided Tours! 

Wonderful small tutorials and interactive how-to guides. All conform to the Diátaxis principles: imperative style, leaving out explanations and extra information, just steps to accomplish a goal, always leading to a positive outcome. 

Joomla’s Help Pages: Reference

Core pages in Joomla’s backend have a Help button. 

After clicking the Help-button a modal window pops up with a page that describes the possibilities of that page: which fields you can fill in and what else you can do on that page. It is typical reference material in the sense of the Diátaxis framework: a complete overview of all things you can do on that page, not much instructions and explanations. At the bottom there often are links to related help pages.

The Help-pages are translated in different languages. The help-pages themselves are momentarily hosted in our documentation site docs.joomla.org, but they might be moved to a Github repository, more a part of the release cycle of the CMS. 

The developers manual

A growing amount of documentation targeted at developers has been adapted from the Joomla 3 documentation in our old docs.joomla.org site to manual.joomla.org. Updates are being made via pull requests on Github. Translations are no priority now. The data is rendered on the website using Docusaurus.

Updating and maintenance of that developers manual is momentarily done by some developers. The principles of Diátaxis are not explicitly applied in the manual (yet). First priority there is to get the developer documentation more or less complete. 

The Wiki

And then we have our good old docs.joomla.org site, also known as JDocs or the Wiki (because it is based on WikiMedia software). For almost two decades all information about Joomla was put into it, lots of people have contributed to it and made translations, a total of 9700 content pages, but it has become messy and out of date. We have to tame that beast! We are working on other systems to host the content, see this article about the future of JDocs last month,  but wherever we go, we still have to update the content.

Some information in the Wiki is a bit disconnected from the rest:

• The Help pages. A reference for each page in the CMS backend. Updated to the latest Joomla version. Could be taken out of the Wiki.
• The Developer Manual. Links are being placed in the Wiki, to convey that newer information is being found in manual.joomla.org.
• General information about the Joomla project and its community. This should be placed on diverse joomla.org pages, like the Joomla Volunteers Portal and others.

We are now focussing on the rest of the content in the Wiki: what articles are worth migrating and updating? 

Migration and new content: with Diátaxis!

We want to set up better user documentation with the help of the Diátaxis method. A dual strategy is to work both:

• Bottom up: reuse old content from the Wiki that is worth updating and migrating to a new documentation system.
• Top down: look for what new documentation is needed and fill in the gaps. For this we should in the first place look at user needs: what are the most frequent and urgent questions on the forum and other help sites? For instance questions about SEF URLs or using SMTP mail on the site.

According to Daniele Procida, the creator of the Diátaxis framework 80% of the work will probably have to be put in good tutorials.

So that must be our first priority for the content of our user documentation: 

• Creating good tutorials that answer most asked questions.
• Reusing and updating existing content where possible.
• Creating new content where needed.
• Guided by the Diátaxis methodology. 

Diátaxis, some resources

• website: diataxis.fr (although .fr is the country code top-level domain for France, it was meant here as a kind of "framework" TLD 😀)
• video of talk “What nobody tells you about documentation”, Daniele Procida, PyCon Australia 2017
• videos of Python Docs Community workshop 2022, by Daniele Procida, part 1 and part 2.