Guide de rédaction de la documentation

Ce guide fixe le style commun à toute la documentation Navin (Plateforme, Navin Manager, agent Navin, services, SDK, API, skills et plugins). Chaque page existe en français et en anglais, avec le même nom de fichier, les mêmes titres dans le même ordre et les mêmes exemples. Le site de documentation est construit par tools/docs/build.py et vérifié par tools/docs/check.py (couverture à 100 %).

Types de pages

Type	Rôle	Titre
Concept	Expliquer ce qu'est un élément, pourquoi il existe et comment il s'articule avec le reste.	Un nom : « Haute disponibilité des services »
Tâche	Faire une chose, étape par étape, de bout en bout.	Un verbe : « Installer le Navin Manager sur RHEL 9 »
Référence	Lister chaque option, champ, commande, code d'erreur ou port, sans exception.	Un nom : « Référence de configuration »
Tutoriel	Un parcours complet pour apprendre, avec un résultat visible.	« Démarrer avec ... »
Dépannage	Symptôme, cause, correction.	« Dépanner ... »
Notes de version	Nouveautés, changements, corrections et problèmes connus d'une version.	« Nouveautés de la version 1.0 »

Modèle d'une page de tâche

Chaque étape explique ce qu'elle fait et pourquoi, donne la commande exacte, le résultat attendu et quoi faire si elle échoue.

# Installer le Navin Manager sur RHEL 9

Un paragraphe : ce que l'on obtient, qui fait l'opération (rôle), la durée indicative.

## Avant de commencer

- Système : RHEL, Rocky ou Alma 9 (x86_64). Vérifier : `cat /etc/os-release`.
- Droits : un compte avec `sudo`.
- Réseau : port 8443 ouvert vers les postes des opérateurs.

## Étapes

1. **Ajouter le dépôt de paquets.** Le dépôt interne fournit les paquets signés ; sans lui, `dnf` ne trouve pas
   le paquet.

   ```bash
   sudo dnf config-manager --add-repo <url-du-depot>
   ```

   `<url-du-depot>` : adresse du dépôt miroir de votre organisation.

   Résultat attendu : `dnf repolist` affiche le dépôt `navin`.

   En cas d'échec : vérifiez le proxy (`/etc/dnf/dnf.conf`) et le certificat du dépôt.

2. **...**

## Vérifier

Commande ou écran qui prouve que l'opération a réussi, avec la sortie attendue.

## Étapes suivantes

Liens vers la suite logique du parcours.

## Dépannage

| Symptôme | Cause | Correction |
| --- | --- | --- |

Modèle d'une page de référence

Une table par groupe, une ligne par option, aucune option omise, aucun « etc. » :

Nom	Type	Défaut	Obligatoire	Description	Exemple

Les valeurs (noms, types, défauts, bornes, codes) sont relevées dans le code source, jamais supposées. Une page de référence tirée du code est générée par un outil (--check signale une page périmée) plutôt qu'écrite à la main.

Règles d'écriture

• Un seul titre de niveau 1 par page (le titre), puis des sections ## et ###, sans sauter de niveau.
• Première phrase : ce que la page permet de faire ou de comprendre. Ajoutez en tête un description: d'une ligne si la page apparaît dans une liste de cartes.
• Phrases courtes, voix active, présent. On s'adresse au lecteur (« vous »).
• Éléments d'interface en gras avec leur libellé exact : Services > Installer.
• Commandes dans un bloc de code avec son langage (bash, yaml, json, python, ts, go, java, sql, text), prêtes à copier. Les valeurs à remplacer sont écrites <entre-chevrons> et expliquées juste après.
• Encadrés : :::note, :::tip, :::info, :::warning, :::danger, fermés par :::, entourés de lignes vides. :::warning pour un risque de panne, :::danger pour une perte de données ou de sécurité.
• Liens relatifs vers le fichier .md cible du même arbre (../operations/upgrade.md#avant-de-commencer).
• Noms de produits jamais traduits : Navin Platform, Navin Manager, agent Navin, Control Plane.
• Typographie : pas de tiret long ni de tiret moyen (U+2014, U+2013) ; utilisez - ou reformulez. En français, accents et espaces avant : ; ? !.
• Interdits : « TODO », « à venir », « bientôt », lorem ipsum, captures avec des données réelles, secrets, adresses internes réelles. Exemples : marqueurs entre chevrons (<control-plane-url>, <harbor-host>, <token>), jamais une adresse inventée.
• Paires de langues : la page anglaise et la page française disent la même chose ; une mise à jour touche toujours les deux.

Numérotation et ordre

L'ordre d'une rubrique suit le parcours du lecteur : vue d'ensemble, installation, configuration, utilisation, exploitation, sécurité, référence, dépannage. Un en-tête sidebar_position: <n> fixe la place d'une page dans le menu quand l'ordre alphabétique ne convient pas.