La documentation du projet

, par Conseil Collégial

Écriture de la documentation

Lors de la journée du 19 janvier 2019, on a abordé la problématique de l’écriture de la documentation dans le cadre de l’arrivée prochaine de la version SE4 du projet SambaÉdu.

Avec Franck, on a vu quelques indications au sujet de l’écriture de cette documentation avec Scenari. Ce logiciel est proposée par une communauté très active.

 

Utilisation de Scenari

Un serveur Scenari a été installé dans un container sur une des machines mises à disposition par Néofutur : il pourra donc être facilement accessible à distance par tous les rédacteurs potentiels de la documentation, une fois qu’un compte sur ce serveur leur aura été attribué.

Dans le passé, de telles documentations ont été réalisées pour SE3 (par exemple pour les clients-linux ou l’importation des données pour la gestion des comptes en début d’année scolaire) et le rendu, ainsi que les possibilités offertes aux rédacteurs, est plus agréable que ce que propose le format markdown que nous utilisons sur le GitHub du projet.

 

Le modèle Dokiel

Le modèle Dokiel serait le plus adapté car orienté « écriture de documentation » (comme son nom l’indique) mais il reste à maîtriser son utilisation : il sera donc proposé un atelier Scenari/Dokiel de 2h lors du prochain HackingSambaÉdu, prévu mi-mars.

 

Participer à l’écriture de la documentation

La prise en main de Scénari n’est pas super évidente et demande un temps de travail pour se familiariser avec cet outil ; pour faciliter son utilisation, on peut envisager la mise en place de modèles (« templates » ou calques) une fois que nous maîtriserons nous-mêmes l’outil.

Cela consisterait à définir une structure type et le rédacteur débutant pourrait, dans un premier temps, se contenter de remplir des boites vides avant d’évoluer vers des modifications plus élaborées lorsqu’il aura ainsi acquis plus d’expérience.