documentation/CONTRIBUTING.md

Contribution

Merci de contribuer à la documentation ! Même si le déploiement/la maintenance des différents services du Crans peut paraître plus intéressante que faire de la documentation, il s'agit au même titre d'une étape cruciale du bon fonctionnement du Crans : on ne peut pas faire fonctionner tout un parc informatique si on ne sait pas ce qu'il y a dedans.

Contribuer

Toute contribution est la bienvenue ! Surtout n'hésitez pas à demander de l'aide aux vieilles nounous si vous n'êtes pas certain⋅e de ce que vous faites.

On distingue ici deux types de contributions :

• les contributions directes, c'est-à-dire un ajout d'une documentation sur un ou plusieurs sujet, ou une modification d'une documentation déjà existante pour la corriger, la mettre à jour, ...

• les demandes de contribution, c'est-à-dire les demandes d'ajout de documentation sur un sujet que vous trouvez mal expliqué et que vous ne comprenez pas bien (sinon vous pourriez le faire vous-même ^^), ou les demandes d'ajout de tutoriels dans le dossier howto.

Pour les demandes de contribution, vous pouvez directement demander à une nounou, mais pour ne pas oublier il vaut mieux dans tous les cas ouvrir une issue sur le dépôt gitlab https://gitlab.crans.org/nounous/documentation. Une nounou ou un⋅e apprenti⋅e se chargera alors (lorsqu'iel aura le temps) d'écrire cela.

Pour les contributions directes, il n'y a aucun problème à directement mettre vos modifications sur ce dépôt, à partir du moment où les modifications/ajouts respectent l'organisation décrite dans la section Organisation du README.md ainsi que les conventions de rédactions décrites ci-dessous. Si vous avez effectué ou prévoyez beaucoup de modifications, il peut alors être préférable de placer tous les changements sur une autre branche puis de faire une merge request sur gitlab pour qu'une autre nounou vérifie vos changements. De plus, si besoin, vous pouvez vous aider des fichiers TEMPLATE.md pour avoir une idée de comment structurer votre documentation.

Conventions de rédaction

Structuration

Tous les fichiers doivent être écrits en markdown. Cela permet de lire toute la documentation dans toutes circonstances avec des mises en forme standardisées. Vous pouvez trouver de la documentation markdown sur ce site si nécessaire. Un linter est configuré dans ce dépôt : markdownlint. Aucun fichier ne doit renvoyer d'avertissement après exécution de la commande mdl . à la racine du dépôt.

Tout dossier doit contenir un fichier README.md, même si celui-ci est court. Il doit contenir le rôle de ce que contient le dossier avec une brêve description de tous les fichiers et sous-dossiers présents.

Tout dossier peut également contenir en plus, si nécessaire et approprié, un fichier TEMPLATE.md mettant à disposition un template pour les futures documentations.

De plus, mis à part les fichiers README.md et TEMPLATE.md, et les fichiers uniques CONTRIBUTING.md, CRITICAL.md et LICENSE.md, tous les noms de fichiers doivent être clairs et en minuscules. Il vaut mieux un nom long qu'une abrévation peu compréhensible. Dans le cas d'un nom de fichiers de plusieurs mots, on les séparera par des tirets bas (underscores). Par ailleurs, on évite autant que possible de créer des dossiers contenant 50 fichiers : on préfère avoir des sous-dossiers thématiques plus navigables.

Mise en page

Il n'y a jamais assez d'hyperliens : n'hésitez pas à mettre des références vers de la documentation officielle ou à rediriger vers d'autres fichiers de la documentation du Crans si cela est possible ! Cela permet de naviguer facilement sans se perdre dans les sous-dossiers.

De plus, pour faciliter la lisibilité, que ce soit dans le terminal ou sur internet, on limite la taille des lignes à 80 caractères en comptant les caractères non affichés sur des rendus graphiques (comme les hyperliens ou les étoiles pour les mots en gras/italique/...). Si besoin, vous pouvez facilement configurer un formatter dans votre éditeur de texte (vim, helix, ...) avec simplement la commande fold -s -w80.

Langue

• Il serait préférable que toute la documentation soit (au minimum) être écrite en français. Cela ne signifie pas qu'il ne peut pas y avoir de traduction en anglais ou de termes informatiques anglais, mais la langue de rédaction devrait rester le français pour être compris par tous et toutes sans difficulté.

• On privilégie le vouvoiement au tutoiement.

• L'usage de l'écriture inclusive est recommandé, que ce soit par l'utilisation prioritaire de termes épicènes, par la coordination (ex: "tous et toutes") ou par l'emploi du point médian.