100 lines
4.9 KiB
Markdown
100 lines
4.9 KiB
Markdown
# 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`](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](README.md#organisation) 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](https://fr.wikipedia.org/wiki/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](https://www.markdownguide.org/) si nécessaire. Un linter est configuré
|
|
dans ce dépôt : [markdownlint](https://github.com/markdownlint/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`](CONTRIBUTING.md), [`CRITICAL.md`](CRITICAL.md) et
|
|
[`LICENSE.md`](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.
|