Contribuer à la documentation

La documentation est versionnée avec le comportement qu’elle décrit. Une PR fonctionnelle met à jour le guide, la story ou le contrat concerné au lieu de créer une tâche documentaire indéfinie.

Choisir la source de vérité

Contenu	Emplacement
Procédure utilisateur du back-office	web/documentation/src/content/docs/utilisateurs
Architecture et workflow transverse	web/documentation/src/content/docs/developpeurs
Exploitation du portail	web/documentation/src/content/docs/exploitation
Détail interne backend	backend/docs
Contrat HTTP	backend/docs/openapi.yaml
Composant, props et états UI	story à côté du composant
Décision structurante durable	ADR daté ou guide d’architecture dédié

Évitez de recopier un catalogue d’endpoints dans plusieurs fichiers. Le guide explique les conventions ; Scalar fournit la référence exhaustive générée.

Structure d’une page

Une bonne page répond à une tâche précise et contient :

1. titre et description frontmatter ;
2. contexte et prérequis ;
3. procédure ou règles ;
4. exemple réaliste sans donnée sensible ;
5. résultat vérifiable ;
6. erreurs et précautions lorsque nécessaires ;
7. liens vers les sources de vérité voisines.

Utilisez des titres orientés action et des paragraphes courts. Définissez un terme lors de sa première apparition. Les commandes doivent être copiables et indiquer leur répertoire d’exécution.

Ajouter une page

1. Créez le fichier sous le bon dossier de documentation/src/content/docs.
2. Ajoutez title et description.
3. Ajoutez son slug à la section correspondante de documentation/astro.config.mjs.
4. Reliez-la depuis les pages adjacentes si le parcours le justifie.
5. Exécutez le formatage et le build.

Starlight génère automatiquement la table des matières à partir des titres de niveaux 2 et 3.

Schémas et images

Placez les assets versionnés sous documentation/src/assets/<section>. Référencez-les avec un chemin relatif et un texte alternatif descriptif :

![Flux d’une requête Le Clos des Eucalyptus](../../../assets/developpeurs/flux-frontend.svg)

Préférez SVG pour un schéma, JPEG/WebP pour une capture et PNG lorsqu’une transparence est nécessaire. Une capture :

• utilise des données fictives ;
• ne montre ni token, URL privée, e-mail réel ou secret ;
• se limite à la zone utile ;
• est remplacée lorsque l’interface change significativement.

Un schéma explique une relation ou un flux ; il ne doit pas répéter un paragraphe simple. Fournissez un title et une desc dans un SVG accessible, ainsi qu’un alt dans le Markdown.

Contrat OpenAPI

Le script de synchronisation copie une source vers documentation/public/openapi.yaml. Pour tester la branche backend locale :

HARMONY_BACKEND_DIR=../backend npm run docs:dev

Ne modifiez jamais le fichier généré sous public. Si la CI web ne peut pas lire le dépôt backend, mettez à jour l’instantané documentation/openapi.yaml depuis le contrat backend validé.

Documentation des composants

Chaque petit composant présentatif possède une story CSF 3 avec des données réalistes et un état par variante significative : défaut, vide, chargement, erreur, sélection ou traitement. Importez Meta et StoryObj depuis @storybook/svelte.

Storybook documente l’API visuelle et interactive ; Starlight explique comment développer et exploiter le système. Liez Storybook au lieu de recopier toutes les props dans un guide général.

Ton et exactitude

• Décrivez le comportement présent, pas une fonctionnalité envisagée.
• Vérifiez les noms des menus, scripts, variables et fichiers dans le code.
• Distinguez obligation technique, convention d’équipe et recommandation.
• N’utilisez pas « simplement » ou « évidemment » pour masquer un prérequis.
• Signalez l’environnement auquel une commande destructive s’applique.

Validation

Depuis web/ :

npm ci --prefix documentation
HARMONY_BACKEND_DIR=../backend npm run docs:check
HARMONY_BACKEND_DIR=../backend npm run docs:build

docs:check synchronise OpenAPI, exécute astro check et Prettier. docs:build génère toutes les pages, optimise les images, construit l’index de recherche Pagefind et le sitemap.

Ouvrez ensuite les pages modifiées, vérifiez la navigation, les liens, les images, le mode sombre et une largeur mobile.

Definition of done

• La bonne source a été modifiée sans duplication inutile.
• Les commandes et chemins ont été exécutés ou vérifiés.
• Les exemples ne contiennent aucune donnée sensible.
• Les images ont un texte alternatif et s’affichent au build.
• OpenAPI et Storybook sont à jour si le comportement les concerne.
• npm run docs:check et npm run docs:build passent.
• La PR explique l’impact documentaire.