Documentation NGOT Client#

Cette documentation regroupe un ensemble de règles, bonnes pratiques et astuces pour écrire la documentation de NGOT pour les clients.

Ces règles ne servent pas à limiter la créativité mais seulement à rendre l'ensemble de la documentation le plus homogène possible.

Règles#

La documentation NGOT est écrite en français et en anglais ;
Les mots n'étant pas dans le dictionnaires (emprunts à d'autres langues, comme plugin ou merge) sont possibles, mais il faut les mettre en italiques ;
Les noms des logiciels prennent une majuscule (ce sont des noms propres). Mais des exceptions existent :
- systemd : l'usage veut qu'il ne prenne pas de majuscule autrement qu'en début de phrase (cf Wikipedia et Github),
Les mots ne contiennent pas de majuscule à l'intérieur du mot. Mais des exceptions existent, en particulier sur les marques ou noms de logiciels :
- CentOS,
- GitLab.
Les listes à puces doivent être homogènes au niveau de leur ponctuation.
- il existe des règles. Wikipedia a pour référence le Lexique des règles typographiques en usage à l'Imprimerie nationale, ouvrage qui n'est pas accessible librement.
- pour la documentation en français, nous pouvons donc reprendre celles de Wikipedia publiées ici,
- pour la documentation en anglais, celle-ci semble simple,
- lorsque les éléments de la liste se répartissent sur plusieurs lignes, avec éventuellement des blocs de code, il faut les indenter. Cela sert à distinguer si les lignes appartiennent à la liste ou si elles démarrent un nouveau paragraphe après la liste,
- en français, les ponctuations doubles (!?:;) doivent être précédées d'une espace insécable. Dans certains logiciels, on l'écrit <AltGR><Maj><espace>. Dans Vim, on peut l'écrire <Ctrl-k> <espace> <espace>.

Bonnes pratiques#

Documentation NGOT#

Dire plutôt contacter l'équipe NGOT via l'adresse mail contact.ngot@orange.com. Éviter contacter le support.
Dire GitLab(ext) (noter les 2 majuscules). On ne dit pas Gitlab.

Documentation en général#

Certaines tournures de phrases récurrentes peuvent être améliorées simplement.

Éviter autant que possible les verbes avoir, être et faire (mais ne pas oublier que avoir et être sont des auxiliaires dont on ne peut pas se passer).
Éviter il y a qui peut se remplacer par des verbes d'état (il y a 3 résultats devient par exemple 3 résultats sont générés ou 3 résultats peuvent apparaître...).

Style :

italique : pour les mots qui ne sont pas dans le dictionnaire ;
- les acronymes restent en normal, mais en majuscules. Exemple : CPU,
- les noms propres restent en normal. Exemple : Kubernetes,
code (chasse fixe) : pour les termes techniques que l'on retrouve dans les fichiers (que l'on peut copier/coller). cela inclut les noms des fichiers/répertoires ;
gras : sert à mettre un mot en valeur. Il faut l'utiliser avec parcimonie sinon plus rien n'est en mis en valeur. En général, on l'utilise pour les présentations et moins dans la documentation.

Images :

Une image s'ajoute ainsi : ![descriptif court de l'image](lien vers l'image) ;
Afin de ne pas consommer inutilement de l'espace disque dans Gitlab avec des fichiers binaires (git n'a pas été conçu pour cela), il faut chercher à réduire la taille des images :
- en diminuant leur taille (en général, 4000x2000 est trop grand, 1500x750 suffira amplement),
- en choisissant le meilleur format (souvent, jpg sera meilleur que png au niveau de la taille, pour une différence de qualité imperceptible),
- en diminuant la qualité de l'image (avec ImageMagick : convert -quality "80%" source.png destination.jpg).

Astuces#

La table des matières s'indique avec [[_TOC_]]. On ne peut pas interagir avec son contenu sur GitLab (contrairement à d'autres moteurs de Markdown).
Pour éviter que le titre ne fasse partie de la table des matières, on peut utiliser du Katex (dérivé de Latex) :
```
$`\Huge{\bold{\text{VOTRE TITRE ICI}}}`$
```
Pour les notes, remarques, points d'attention, il est possible d'utiliser des emoji de cette façon :
```
>>>
⚠️  Attention

Votre point d'attention ici
>>>
```
Le résultat est approximativement le suivant dans GitLab :

⚠️ Attention

Votre point d'attention ici

Voici quelques autres emoji utiles :
```
-  ⚠️  Attention
-  ❌ Danger
-  ⛔ Forbidden
-  🚨 Warning/Important
-  ✅ Affirmation
-  ‼️ Exclamation
-  🚫 Prohibited
```
Lorsqu'un verbe n'est pas dans le dictionnaire, on peut le mettre en italiques mais il faut éviter d'utiliser la conjugaison française pour un verbe non français. Il est possible de transformer la phrase pour que le verbe devienne un nom et il est plus simple de l'utiliser tel quel. Par exemple merger dans GitLab deviendrait dans GitLab, cliquer sur merge. Parfois, il est également possible d'utiliser le mot français et de mettre entre parenthèses le terme anglais. Par exemple : métriques rejetées (dropped).