Mise en place documentation

Documentation et traduction
1

Salut tout le monde,

J’ai jeté un oeil aux solutions pour mettre notre documentation en ligne (ça fait partie des objectifs NLNet).

Je m’en tiens aux outils de documentation technique, parce qu’on peut aussi aller chercher des moteurs de blog, etc… mais ils vont manquer des fonctionnalités propres aux docs techniques.
En gros, il y’a 2 outils largement utilisés, maintenus, etc…

À mon sens, il faut un outil qui puisse:

  • gérer le markdown pour rédiger la doc (à peu près tout le monde sait s’en servir, sinon c’est facile à apprendre). RST (ReStructured Text) est courant aussi, mais c’est galère.
  • se mettre en route facilement, et se gérer de la même manière
  • être intégré avec notre base de code/CI, de façon à se mettre à jour automatiquement
  • idéalement, être supporté par readthedocs ou équivalent, genre gitlab pages, pour qu’on puisse déployer chez eux, et ne pas avoir à gérer encore un service/serveur.

Sphinx

Probablement le plus ancien, solide, etc… Super riches en fonctionnalités, mais ça se paie en complexité de mise en route/maintenance.
Il y’a des extensions telles que MyST qui permettent de gérer le markdown (historiquement, sphinx ne fait que du RST), donc ça fera tout ce qu’on veut et plus.

MkDocs

Plus récent, basé sur markdown (c’est un peu une exagération de dire ça, vu qu’il y’a 143582459 versions de markdown, mais bon…), un peu moins riche en fonctions, mais il semble plus facile à améliorer, et tous les projets « cool » du moment ont l’air de s’en servir, probablement parce que c’est plus facile à prendre en main. Il y’a encore des fonctions que sphinx gère mais pas MkDocs, mais je ne pense pas qu’on en ait besoin de suite, et MkDocs évolue aussi très vite, donc il est probable que si quelque chose nous manque, ça ne dure pas longtemps.

Du point de vue visuel, voilà quelques exemples de sites qui me semblent lisibles et facile à naviguer autant sur ordi que mobile:

Dites moi si vous avez des opinions/expériences avec ces outils, et une préférence. Mon but est de mettre la doc en place rapidement, pour qu’on puisse se focaliser sur l’écriture/mise à jour.
Je compte rassembler toute la doc Ma Dada sous https://docs.madada.fr (ou doc.madada.fr?) avec des sections utillisateurs/administrations/PRADA/technique bien séparées.
Ça vous semble bien?

3

C’est fait! Devant le déluge de réponse, j’ai choisi tout seul (avec l’aide d’Eda en visio hier) :slight_smile:

https://doc.madada.fr

L’outil est super bien fait, en particulier, vous noterez:

  • « dernière mise à jour » au bas de chaque page
  • un lien vers le code source en en-tête
  • une icône « stylo » pour éditer la d’oc directement dans gitlab. Il suffit d’avoir un compte gitlab pour pouvoir faire une MR.
  • je vais ajouter un lien vers le forum pour les non-techniques afin de pouvoir suggérer des modifications

Merci @pascalr pour tout le contenu, c’est en ligne, j’ai juste réorganisé les fichiers pour avoir une navigation décente.

J’espére qu’on va arriver à remplacer la doc existante avec ceci, c’est le jour et la nuit en termes de maintenance.

La doc est déployée automatiquement à partir de la branche doc-public, pour ne pas bloquer le code du site, et vice-versa.

4

Vous avez bien fait, l’outil a l’air top ! Et ce sera facile à actualiser.

Du coup, comment gère-t-on par rapport aux pages d’aide (A propos - Ma Dada) sur le site ? Est-ce qu’on renverrait directement vers cet outil de doc pour éviter de maintenir deux documentations ?

5

Ce qu’on pensait avec Eda, c’est de transférer le contenu des vieilles pages vers les nouvelles, puis de carrément supprimer les anciennes pages une fois que c’est fait.