Dans une salle de conférence d'un hôtel à Darmstadt, en Allemagne, une petite équipe de passionnés de Joomla s'est familiarisée avec Docusaurus, apprivoisant la bête au profit de la communauté des développeurs Joomla. Cet ensemble de logiciels soigné est probablement le changement le plus important dans la documentation Joomla depuis longtemps, et avec le bonus supplémentaire de tuer le redoutable captcha MediaWiki une fois pour toutes !
L'équipe qui s'est réunie le 24 juillet 2022 à Darmstadt, en Allemagne, était composée de :
Benjamin Trenkle (DC Production), Philip Walton (DC Outreach), Mike Brandner (TL JDocs Team), Christiane Maier-Stadtherr (TL Joomla Accessibility Team), Viviana Menzel (TL Accessibility Team) et via en ligne Shivam Rajput (TL Enhancement Development Team et Google Summer of Code Joomla Team) et également en ligne Harald Leithner (DC Operations).
La réunion avait plusieurs objectifs clés :
- Trouver la clarté dans l'avenir de JDocs,
- Préparez-vous pour la candidature à Google Season of Docs
- Comprendre le nouveau logiciel de Documentation Développeur et le rendre opérationnel.
Projets prévus pour le GSoD
Les projets prévus pour le GSoD ont été présentés et discutés.
La documentation pour les développeurs était le premier projet. Il y a eu une tentative de résoudre ce problème plus tôt dans l'année, mais cela n'a pas été poursuivi. Nous avions besoin d'une solution.
Harald a présenté Docusaurus 2, un outil open source de Meta, qui est disponible sur GitHub et prend en charge la documentation versionnée.
Le consensus général était qu'il s'agit d'un très bon outil pour commencer la documentation de nouvelles fonctionnalités.
GitHub : https://docusaurus.io/
Le deuxième projet était une documentation conviviale pour Joomla! Utilisateurs, le "Guide de l'utilisateur Joomla". Il y a eu beaucoup de retours des utilisateurs de Joomler. Beaucoup trouvent les JDocs actuels trop compliqués à utiliser, il y a un niveau d'entrée assez élevé donc ce n'est pas propice à l'autodidacte. La documentation appropriée provenant de sources externes qui donnent les bonnes réponses est également difficile à trouver.
Pour ce deuxième projet, nous avons décidé de créer un site Web autonome comme source de documentation conviviale. Cela ne signifie pas nécessairement la fin des JDocs avec MediaWiki, juste un autre site Web qui contient quelque chose comme le manuel d'utilisation de Joomla. Clairement structuré et uniquement avec des contenus pour les versions prises en charge.
Pour les deux projets, la page JDoc pour GSoD 2023 a été créée et remplie d'informations initiales : https://docs.joomla.org/GSoD_2023
L'idée est d'obtenir une subvention de GSoD pour financer des rédacteurs techniques. Ils feront ensuite avancer le projet, soutenus par les mentors des projets. Trop souvent, l'élan s'est épuisé, alors cette approche comblera, espérons-le, le fossé entre le besoin et la réalité qui nous échappe si souvent.
L'atelier principal
Dans l'atelier suivant, le nouveau Joomla! La documentation du développeur a été expliquée et tous ceux qui se trouvaient dans la salle ont commencé à la configurer ensemble. Benjamin a aidé avec des problèmes techniques, mais le système est simple. La structure initiale a été créée; voir : https://github.com/joomla/Manual
Une fonctionnalité intéressante est que la documentation est écrite dans le balisage et gérée via GitHub, ce qui est beaucoup plus intuitif que MediaWiki (du point de vue d'un développeur).
Afin de maintenir à jour la documentation du développeur, il est également prévu d'exiger une entrée Dev Docs pour chaque PR de fonctionnalité à partir de Joomla 4.3, avant qu'elle ne puisse être fusionnée. Le manque de bonne documentation a été la malédiction de tant de projets logiciels, et Joomla n'a pas fait exception. Pour résoudre ce problème, nous devons prendre la documentation aussi au sérieux que le code qu'elle documente.
Les plans du projet "Guide de l'utilisateur Joomla" ont été discutés. Il n'y a pas encore de plans concrets pour la plate-forme qui sera utilisée, et nous sommes ouverts aux suggestions. Une idée était d'utiliser Joomla comme plate-forme ; peut-être existe-t-il un outil mieux adapté, et nous apprécions vos commentaires.
La gestion des traductions pourrait être gérée via Crowdin, nous avons donc déjà un système établi pour gérer cela.
Vers la fin de l'événement, la discussion s'est tournée vers la destination de la documentation Joomla. Au cours de nos discussions, il est devenu clair que les JDocs existants devaient être maintenus et exploités comme une plate-forme de documentation pour la communauté. Les pages d'aide sont déjà configurées, nous ne pouvons donc pas trop changer, bien qu'il puisse être prévu d'automatiser une partie de ce processus.
Ce dont les utilisateurs ont désespérément besoin, c'est d'une documentation que les utilisateurs peuvent utiliser pour s'y retrouver facilement. C'est le chemin que nous aimerions emprunter avec le "Guide de l'utilisateur Joomla".
Votre rôle dans le plan
Cela impliquera beaucoup de travail, pour lequel nous aurons besoin de nombreux contributeurs, alors pensez à donner un peu de votre temps. Si vous avez déjà souffert d'un manque de documentation, c'est le moment idéal pour vous manifester et aider à résoudre ce problème, afin que d'autres n'aient pas le même problème.
Si vous souhaitez soutenir le projet, n'hésitez pas à contacter l'équipe JDocs ou à envoyer un message direct via Glip ou par e-mail à
