Rédaction d'une documentation

Le format markdown sur le dépôt c'est très bien. Vit dans le repo, à côté du code : un USAGE.md par module métier, versionné avec lui. On préfèrera un dossier docs complet à une doc répartie partout.

Critères

• Elle documente ce qui ne peut pas l'être dans le code (les flux métiers), ou ce qui ne l'a pas été pour des raisons historiques. Ou alors elle documente un élément nécessaire car on le rencontrera vite et on ne pensera pas forcément à chercher de ce côté (ex : en staging les mails vont dans Mailtrap pour les emails @a1 et sont réellement envoyés pour les autres emails)
• Plus elle est courte, meilleure elle est
• Elle documente les usages qu'on en a, plus que le statut du code
• Répond à des questions qu'on s'est vraiment posées — en prod, en debug, en onboarding
• Est écrite au moment où quelqu'un l'explique à voix haute, ou après 30 min de debug sur quelque chose d'opaque
• Ne peut pas être générée par une IA en 2-3 prompts — si elle peut, c'est qu'elle documente le quoi, pas le pourquoi ni le comment on s'en sert vraiment. Elle crée plus de bruit qu'autre chose, bruit qui s'outdate par rapport à la codebase. Une partie sera nécessairement générée par IA ; sur cette partie, utiliser un skill d'expert de rédaction de doc (présent dans le dépôt parent)
• Ne pas documenter les méthodes et leurs paramètres — une IDE ou une IA peut les lire directement depuis le code. Ça documente le "quoi" sans apporter aucune valeur, et ça s'outdate dès qu'on renomme un paramètre
• Préférer une doc dynamique quand c'est possible (Swagger pour les APIs, introspection DB, JSDoc généré) — elle reste synchronisée avec le code automatiquement, contrairement à un Markdown maintenu à la main qui s'outdate

Exemples

• ❌ Mauvaise doc : "Il existe une route qui permet de déclencher une réindexation"
• ✅ Bonne doc : "Il existe une route de réindexation dans l'admin, et d'ailleurs on l'utilise avec tel et tel paramètre ; elle timeout parce que la réindexation prend environ 5 minutes et sur les apps on a un timeout de 30s"
• ✅ Bonne doc : "Pour déployer, on fait …"
• ✅ Bonne doc : "Pour aller voir les logs en prod on fait …"
• ✅ Bonne doc : "En local il manque certaines variables d'environnement, ce sont celles-ci car on utilise les APIs de prod"