De staat van Joomla's documentatie

Gepubliceerd: 7 december 2024.Door: Ton Kemp.Categorie: Magazine.

De Joomla-documentatie is een verzameling handleidingen, tutorials, referenties en andere informatie die gebruikers en ontwikkelaars helpt om met Joomla te werken. Deze documentatie is essentieel om de gemeenschap te ondersteunen bij het leren, implementeren en ontwikkelen van Joomla-projecten. Jouw hulp is nodig bij de update en verbetering.

Waar bestaat de Joomla-documentatie uit?

Gebruikershandleiding:
- Richt zich op beginners en eindgebruikers.
- Behandelt onderwerpen zoals het installeren van Joomla, het maken en beheren van inhoud, en het aanpassen van instellingen.
Ontwikkelaarsdocumentatie:
- Gericht op ontwikkelaars en technische gebruikers.
- Bevat details over het bouwen van extensies (zoals componenten, modules en plug-ins), het maken van templates en het gebruik van de Joomla API.
Beheerdershandleiding:
- Voor sitebeheerders die verantwoordelijk zijn voor het dagelijks beheer van Joomla-websites.
- Onderwerpen omvatten gebruikersbeheer, beveiliging, back-ups en systeemconfiguratie.
API-documentatie:
- Technische referentie die automatisch wordt gegenereerd uit de Joomla-code.
- Bevat uitleg over de functies en klassen in het CMS.
Specifieke hulp-pagina's:
- Contextgevoelige help-informatie die toegankelijk is via de "Help"-knop in de Joomla-beheerdersomgeving.

Waarom is de documentatie belangrijk?

Toegankelijkheid:
- Nieuwe gebruikers kunnen snel leren hoe Joomla werkt.
- Verlaagt de drempel voor deelname aan de Joomla-gemeenschap.
Ondersteuning voor de gemeenschap:
- Helpt vrijwilligers, ontwikkelaars en site-eigenaren om effectief met Joomla te werken.
Bevordering van innovatie:
- Geeft ontwikkelaars de tools en kennis om geavanceerde extensies en functies te creëren

De "oude" documentatie

De officiële documentatie van Joomla is te vinden op docs.joomla.org. Het systeem is gebaseerd op MediaWiki. Het basisidee is: iedereen kan eenvoudig bijdragen. Het heeft ook ingebouwde voorzieningen voor vertalingen. Door de jaren heen is de structuur van de documentatie echter verslechterd en is het steeds moeilijker geworden om informatie te vinden. Het systeem is ontspoord.

Alternatieven voor MediaWiki

GitHub-gebaseerde oplossingen

Enkele jaren geleden gingen enkele Joomlers op zoek naar een alternatief voor MediaWiki. Ze kwamen tot de conclusie dat GitHub een goede basis zou zijn om de documentatie op te slaan vanwege de versiebeheerfunctionaliteit. De nieuwe documentatie zou worden opgeslagen in het markdown-formaat van GitHub, dat algemener is dan de aangepaste wikitext-opmaak.

Twee implementatietypes zijn verkend die beide markdown-pagina’s in GitHub gebruiken:

Docusaurus
- Een open-source Node/Typescript-project van Meta.
- Content wordt bijgewerkt via pull requests.
- Vertalingen kunnen worden beheerd via Crowdin, de officiële vertaalpartner van Joomla.
- Drie toepassingen die al draaien:
  - Developers Manual (manual.joomla.org): Dit heeft prioriteit om compleet en actueel te worden. Het groeit gestaag. Vertalingen worden overwogen na voltooiing.
  - Prototype gebruikershandleiding (docs-next.joomla.org).
  - Interne documentatie voor projectmanagement van Joomla.
JDocManual
- Gemaakt als een Joomla-maatwerkcomponent door Cliff Ford.
- Beheer van content gebeurt binnen Joomla, met ingebouwde taalassociaties.
- Het onderhouden van aangepaste componenten is echter een uitdaging gebleken voor Joomla.

Heronderzoek naar Joomla-only oplossingen

Hoewel eerder GitHub-markdown als beste optie werd beschouwd, wordt nu ook een Joomla-gebaseerde “core only”-oplossing heroverwogen. Een prototype is in ontwikkeling.

Belangrijke uitdagingen en lopende werkzaamheden

Help-pagina's: Er zijn plannen om de Help-pagina's, toegankelijk via de Help-knop aan de Administrator-kant, te migreren naar een apart systeem.
API-documentatie: De referentie op api.joomla.org wordt automatisch gegenereerd via PhpDocumentor vanuit docblocks in de code. Dit vereist weinig aanpassingen, maar wel onderhoud.

Nieuwe leiding en koers

In oktober 2023 nam Herman Peeren het stokje over van Dieter Ziller als teamleider. Dieter leidde het team door een uitdagende periode. Herman brengt decennia aan ervaring mee in ontwikkeling en community-engagement en wil de documentatie grondig vernieuwen.

Doelen voor 2024

Het vergelijken en vaststellen van een strategie voor de documentatie (MediaWiki vs. GitHub vs. Joomla-gebaseerde oplossingen).
Een duidelijke en goed navigeerbare structuur opzetten voor de inhoud.

Visie voor 2025

Tegen oktober 2025, wanneer Joomla 6 wordt uitgebracht, moet de documentatie:

Toegankelijk, compleet en up-to-date zijn.
Nieuwe gebruikers aantrekken met duidelijke handleidingen voor sitebouwers, beheerders en inhoudbeheerders.
Een betrouwbare bron van actuele informatie zijn.

Oproep aan alle vrijwilligers

Om deze ambitieuze doelen te bereiken, is samenwerking essentieel. Tijdelijke teams worden opgezet om verschillende aspecten van de documentatie aan te pakken.

Als je wilt helpen:

Sluit je aan bij het PD Documentation-kanaal op Mattermost en laat weten dat je wilt bijdragen.
Neem direct contact op met Herman (@herman-peeren) via Mattermost.

Jouw vaardigheden en enthousiasme kunnen de toekomst van Joomla helpen vormgeven!

Geplande initiatieven

Het organiseren van documentatiesprints (vergelijkbaar met "Pizza, Bugs & Fun"-bijeenkomsten) met volledige focus op documentatie.
Mogelijk heropleving van het Document Buddies-initiatief, dat niet-programmeurs aanmoedigt bij te dragen aan Joomla.

Notes

Voor meer informatie, bekijk de gerelateerde artikelen en discussies in onderstaande notities.

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
JDocManual, also see (October 2023): https://magazine.joomla.org/all-issues/october/joomla-documentation-a-joomla-solution
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
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

Dit artikel is een bewerking van een artikel uit Joomla Community Magazine
Lees alle artikelen in het magazine via deze link
Joomla! bestaat al 19 jaar als Open Source project. Dat is een lange tijd in technologiejaren! 19 jaar geleden kon je niet eens een iPhone bezitten, of X gebruiken en waarschijnlijk had je geen Facebook-account maar een Hyves-account 😊.
Er is veel gebeurd, maar Joomla! is al die tijd een duurzame keuze gebleken als CMS voor miljoenen websites wereldwijd, ondersteund door een betrokken community.