Aller au contenu principal

Guide de rédaction documentation

Ce guide définit la méthode à suivre pour produire des pages homogènes, utiles et visuellement cohérentes avec le style Superpilote.

Objectif de chaque page​

  • Répondre à un besoin utilisateur concret.
  • Expliquer une action de bout en bout, sans ambiguïté.
  • Reprendre les libellés réels de l'interface (boutons, onglets, champs).
  • Faciliter la lecture rapide avec une structure stable.

Process de création (obligatoire)​

Vérifier le code source avant d'écrire​

  • Retrouver les composants réels frontend liés à la fonctionnalité documentée.
  • Confirmer le vocabulaire exact de l'UI (labels, messages, titres, boutons).
  • Identifier la logique métier visible côté utilisateur (conditions, champs obligatoires, variantes).
  • Relever les icônes réellement utilisées en application pour les réutiliser dans la doc.

Définir le bon angle utilisateur​

  • Partir du cas d'usage: "Je veux faire X".
  • Garder un parcours orienté action (préparer -> faire -> valider).
  • Supprimer les détails techniques internes non utiles au lecteur final.

Rédiger avec une structure standard​

  • # Titre page avec icône principale de la ressource.
  • ## Étapes en couleur primary (sans numéro dans le titre).
  • ### Sous-parties opérationnelles (champs obligatoires, options...) en couleur secondary.
  • Titres de sections orientés action, jamais en question (ex. « Valider une journée », « La fenêtre Boîte à heures ») : les formulations en question sont réservées à la FAQ en fin de page — sinon la page entière se lit comme une FAQ géante.
  • Bloc tip pour une astuce pratique.
  • Bloc note pour une précision utile.
  • Bloc warning pour "Erreurs fréquentes" (sans doubler avec une icône FA).

Ajouter les icônes de façon cohérente​

  • Utiliser FAIcon globalement dans les pages Markdown.
  • Privilégier les icônes duotone (fad) pour garder une cohérence visuelle premium.
  • Utiliser des icônes qui reflètent la ressource réelle (issues du code source).
  • Garder une densité d'icônes raisonnable: clarifier, pas décorer excessivement.

Exemples:

# <FAIcon icon={['fad', 'screwdriver-wrench']} /> [Créer un chantier](/nouveau/creer-un-chantier)
## <FAIcon icon={['fad', 'plus']} /> Ouvrir la création
### Champs obligatoires
- <FAIcon icon={['fad', 'user']} /> **Client**

Aligner la sidebar​

  • L'icône de l'item de menu gauche doit correspondre à l'icône principale de la page.
  • Définir l'icône via customProps.icon dans sidebars.ts.
  • Respecter la cohérence de vocabulaire entre titre de page, titre sidebar et contenu.

Qualité rédactionnelle attendue​

  • Ton direct, clair, orienté résultat.
  • Phrases courtes, vocabulaire simple.
  • 1 idée par phrase.
  • Éviter le jargon technique.
  • Expliquer les erreurs courantes et comment les éviter.

Checklist de validation avant livraison​

  • Les labels et parcours correspondent au produit actuel.
  • Les champs obligatoires/optionnels sont exacts.
  • Les icônes de page et sidebar sont cohérentes avec le code.
  • Les niveaux de titres sont correctement utilisés (#, ##, ###).
  • Les blocs tip / note / warning sont utilisés à bon escient.
  • La page est agréable à lire (rythme, espacements, lisibilité).
  • La page compile sans erreur (pnpm --filter=@supervision/docs-public build).

Relecture finale croisée avec le code source (obligatoire)​

  • Repasser la page complète, section par section, en vérifiant chaque affirmation dans le code source.
  • Confirmer à nouveau tous les libellés visibles (onglets, boutons, filtres, statuts, messages) après rédaction.
  • Vérifier que les procédures décrites correspondent exactement au parcours réel (ordre des étapes, options disponibles, limites).
  • Corriger immédiatement toute divergence détectée entre documentation et application.
  • Ne pas publier tant que la correspondance "doc = réalité produit" n'est pas validée.

Modèle prêt à copier​

---
title: Titre de la page
---

# <FAIcon icon={['fad', 'icone-principale']} /> Titre orienté action

## <FAIcon icon={['fad', 'plus']} /> Ouvrir

- Étape actionnable 1
- Étape actionnable 2

:::tip[Astuce]
Conseil concret qui fait gagner du temps.
:::

## <FAIcon icon={['fad', 'pen-to-square']} /> Renseigner

### Champs obligatoires

- Champ A
- Champ B

### Champs optionnels

- Champ C

:::note[Bon à savoir]
Précision utile au bon moment.
:::

## <FAIcon icon={['fad', 'floppy-disk']} /> Finaliser

- Action finale
- Résultat attendu

:::warning[Erreurs fréquentes]
- Erreur 1
- Erreur 2
:::