Documentation
Conventions d'écriture
Pour que cette documentation soit la plus homogène possible, les conventions d'écriture suivantes doivent être respectées.
Généralités
- utiliser une indentation à quatre espaces
- mettre le nom des logiciels en majuscule
- utiliser des guillemets français : « » avec des espaces insécables
- utiliser les accents graves (``) pour entourer les variables ou termes techniques cités
- sauter une ligne avant une liste
- être concis et efficace, quitte à créer une section « Aller plus loin » en fin de page
- mettre en forme les tableaux dans le texte brut, si besoin s'aider de tablesgenerator
En cas de doute ou de difficulté concernant la syntaxe markdown, se référer aux documentations suivantes : résumé, syntaxe exhaustive, particularités liées à mkdocs
Espacements
Pour une lisibilité optimale de nos fichiers, même non formatés, on veillera à respecter les espacements suivants entre les titres :
# Titre 1
⏎
## Titre 2
⏎
$paragraphe$
⏎
⏎
## Titre 3
⏎
$paragraphe$
Listes
Les listes ne comprennent ni point ni majuscule si leurs contenus ne sont pas des phrases. Sinon, leur syntaxe est celle des paragraphes standards. Pour les listes en cascade, on utilise les trois préfixes possibles en alternance, dans l'ordre -, * et + :
# Titre
⏎
- item de premier niveau
- autre item de premier niveau
* item de second niveau
+ item de troisième niveau
+ autre item de troisième niveau
* autre item de second niveau
+ encore un item de troisième niveau
- un item de quatrième niveau
- et un autre
Pour les listes numérotées, ne pas chercher à compter, markdown s'occupe de tout :
1. fromage
1. bleu
1. morbier
1. pâtes
1. beurre
Codes de décision
Lorsqu'il est fait référence à une décision formelle, celle-ci doit être indiquée avec une formulation et une syntaxe précise, et doit dans le même temps renvoyer à la documentation dédiée aux prises de décision. Par exemple :
[...] doit être approuvé au niveau [CC-CV](/docs/association/decisions#mise-en-œuvre-dune-prise-de-décision)
Pronoms
Pour s'adresser aux lecteurices :
- privilégier les tournures impersonnelles
- utiliser le vouvoiement
Pour parler de la FELINN, alterner le plus possible entre :
- « la FELINN » (et non « La FELINN »)
- « l'association » (et non « notre association »)
- « nous »
Écriture non-invisibilisante
- utiliser le plus possible des tournures et des mots épicènes (e.g. « les personnes ») et des néologismes faciles à lire (e.g. « iels »)
- lorsque cela est possible (lisible), éviter le point médian et lier directement les suffixes (e.g. « utilisateurice », « administrateurice »)
- en cas de recours au point médian, ne pas le dédoubler pour le pluriel (on écrira « ·ices » et « ·euses » et non « ·ice·s » et « ·euse·s »)
Termes techniques
- ne pas écrire différemment les termes techniques entre la documentation utilisateurices et administrateurices
- assumer l'anglais dès que les termes sont par défaut écrits et dits dans cette langue dans les standards et les interfaces (e.g. « issue », « snapshot »)
- utiliser le français dès que la traduction parle d'elle-même (e.g. « sauvegarde »)
Termes génériques
- mail : email
- adresse électronique : adresse email
- application, logiciel, service :
- logiciel : ce dont on se sert pour créer les services (e.g. synapse)
- service : logiciel ou ensemble de logiciels installés sur un container ou une VM pour un usage particulier (e.g. matrix.felinn.org)
- application : ce dont l'utilisateurice se sert pour accéder aux services (peut être une application cliente ou web e.g. element)
Guides d'utilisation des services
Les guides d'utilisation sont à destination des utilisateurices et sont tous consignés dans docs.felinn.org/utilisation/. Ils ont vocation à les accompagner dans la prise en main et l'utilisation de nos services. Au-delà des conventions d'écriture, voici quelques recommandations à suivre pour pouvoir contribuer aux guides d'utilisation des services :
- Articuler le guide en plusieurs parties distinctes, dont a minima Présentation et Utilisation.
- Utiliser des captures d'écran pour illustrer les indications. L'ajout de légendes et de dessins pour améliorer la clarté des images est encouragé (par exemple en utilisant l'application Easy Screenshot pour Firefox).
- Adopter le point de vue des utilisateurices. Sans chercher à infantiliser, un guide doit minimiser l'utilisation de termes techniques et se concentrer sur l'utilisation du service. Cependant, dans une perspective d'autonomisation des membres de l'association, des notions plus avancées et non nécessaires à une utilisation de base peuvent être abordées dans une section « Aller plus loin ».
Protocoles
Pour une grande partie de la gestion associative et technique courante de la FELINN, nous utilisons des protocoles qui font office de documentation (voir par exemple ici). Ces protocoles ont vocation à systématiser nos pratiques, de sorte à rendre celles-ci les plus traçables, compréhensibles et cohérentes possibles. Au-delà de l'efficacité, ces protocoles nous permettent de rendre nos méthodes plus transparentes pour nous utilisateurices.
Évidemment, ces protocoles ne couvrent pas tous les cas de figure possibles. Ils pourront être améliorés et complétés à mesure que nous rencontrerons des nouvelles situations. Pour cela, nous avons rédigé... un protocole !
Créer un nouveau protocole
Conditions préalables
- Avoir un objet unique et précis qui correspond à un besoin concret. Il faut donc vérifier qu'il ne fasse pas doublon ou qu'il ne puisse pas être intégré à un protocole existant (ou inversement).
- Ouvrir une issue dans https://git.felinn.org/FELINN/docs.felinn.org/ en utilisant le modèle « nouveau protocole » titrée "[création] objet du protocole", et dont la description détaille le besoin et l'objectif.
- L'issue doit être approuvée au niveau CC-CV.
- Si approuvée, l'issue doit donner lieu à la rédaction et à des relectures du protocole correspondant.
Écriture du protocole
- doit comprendre un titre clair
- doit comprendre une introduction explicative (objet et objectif)
- doit comprendre une séquence numérotée de procédures à respecter pour parvenir de A à B
- (facultatif) peut être représenté de manière formelle par un graphe UML
Un protocole doit être écrit avec la syntaxe spéciale admonition :
:::protocole
1. faire ci et ça
1. faire cela aussi
:::
Modification d'un protocole existant
Sur le fond
- Ouvrir une issue dans https://git.felinn.org/FELINN/docs.felinn.org/ en utilisant le modèle « modification de protocole » titrée "[modification] objet du protocole", et dont la description détaille les besoins de modification.
- L'issue doit être approuvée au niveau CC-CV.
- Si approuvée, l'issue doit donner lieu à la correction et à des relectures du protocole correspondant.
Sur la forme (mise en page, orthographe, syntaxe)
- si l'utilisateurice n'a pas les droits d'écriture sur le wiki, ouvrir une issue de la même manière que ci dessus
- si l'utilisateurice a les droits d'écriture sur le wiki, iel peut modifier directement le protocole en expliquant l'objet de sa modification dans le commit