Création d'un site de documentation

[cyChop]

La documentation (et plus spécifiquement les guides de contribution et du challenge) sont très complexes à suivre et lire. De simples todo lists renvoient parfois à deux niveaux de liens ou plus. Il est compliqué de garder un fil de pensée lorsqu'il est nécessaire de naviguer en permanence entre plusieurs pages.

Pour palier un problème similaire sur un autre projet, j'ai mis à profit la solution Antora, qui a plusieurs avantages dans ce contexte :

• basée sur Asciidoctor : on peut s'appuyer sur sa fonctionnalité d'inclusion des pages pour extraire les contenus communs dans des partials (sections de contenu à inclure dans des pages) ;
• multi-repo : chaque repo peut contenir sa propre documentation, le build Antora récupèrera ces informations et les intègrera à son build ;
• multi-module : il est possible de documenter plusieurs modules au sein d'un même site (on peut imaginer un module par plugin, et des modules transverses comme "contribution", "challenge"…) ;
• multi-version : on peut afficher différentes versions d'un module, ce qui peut permettre de conserver la documentation de chaque version d'un plugin, par exemple.

Pour la mise à disposition du site, on peut envisager un déploiement sur un sous-domaine (p.ex. docs.ecocode.io).

Une phase d'analyse et définition serait idéalement nécessaire, pour définir la structure du site.

J'ai créé plusieurs sites de documentation avec Antora et j'ai l'habitude de travailler avec Asciidoctor. Je peux initier le travail de "migration" vers cette solution et initier les pull requests associées si elle est retenue par la core team.

Après discussion avec quelques membres de l'équipe, il semblerait pertinent que le job qui "contrôle" le build et le déploiement de la doc soit versionné dans un repo indépendant, par exemple ecocode-docs.