Guide de synchronisation entre documentation et produit
Aligner la documentation publique en quatre langues sur le comportement livré de TianGong LCA.
La documentation publique explique ce que les utilisateurs peuvent faire ; le dépôt produit détermine le comportement réel. Avant de modifier un parcours, une autorisation, une route, une API ou une explication visuelle, vérifiez l'implémentation actuelle dans ../platform.
Sources de vérité
- Comportement produit :
../platform - Source chinoise :
content/docs/**/page.mdx - Anglais, allemand et français : fichiers voisins
.en.mdx,.de.mdxet.fr.mdx - Routage et présentation :
app/**,components/**etlib/** - Médias publics :
public/assets/docs/**
Les quatre fichiers de langue représentent une même page logique. Modifiez ensemble structure, liens, étapes, contraintes et exemples dans le même commit.
Parcours recommandé
- Localiser la route, le composant, le contrôle d'autorisation ou l'API réels.
- Identifier les utilisateurs, rôles, espaces de données et langues concernés.
- Mettre à jour la source chinoise et les trois traductions.
- Vérifier libellés, ordre, états, erreurs et différences de rôle dans l'interface actuelle.
- Exécuter toute la validation documentaire et examiner le rendu dans un vrai navigateur.
Quand utiliser le produit en ligne
Le code seul ne suffit pas lorsque l'entrée dépend d'un rôle, que l'état vient du backend, que la mise en page responsive ou les noms accessibles comptent, ou qu'une capture doit représenter l'expérience réelle.
Ne placez jamais d'identifiants, clés API, valeurs d'environnement ou données privées dans la documentation, les captures, le terminal ou les commits.
Principes pour les captures
- Ajouter une capture seulement si elle réduit nettement l'effort du lecteur.
- Utiliser par défaut l'interface anglaise du produit.
- Préférer un cadrage clair, des libellés lisibles et quelques repères numérotés.
- Réutiliser un même média public dans toutes les langues, avec alt et explication localisés.
- Stocker les médias sous
public/assets/docs/<hash>/<slug>et exiger la réussite du contrôle des liens générés.
Validation
pnpm lint
pnpm typecheck
node --test scripts/check-links.test.mjs
DEPLOY_ENV=ci CANONICAL_ORIGIN=http://localhost:3000 NEXT_PUBLIC_SEARCH_MODE=static pnpm buildPour le visuel, vérifier aussi 390px, 1440px, ultra-large, clair et sombre, ainsi que le focus clavier, la recherche, le changement de langue et le menu mobile.
Une lacune confirmée mais non résolue doit être enregistrée pendant la même session dans TODO.docs-system-gaps.md ou un issue exécutable.