Les pièges a éviter:

• readme cimetière
• theator of documentation: useless comments
• outdate trap: "how" is a wrong answer
• un ROI négatif.(Lectures × Temps gagné) - (Temps d’écriture + Maintenance).

Pour maximiser ce ROI, il faut distinguer quatre types de documentation :

1. ROI Infini : La doc fonctionnelle (le problème). C’est la boussole de la feature. Elle ne décrit pas les boutons, mais la valeur.
   • Le contenu : À quel problème client répond-on ? Quelle est la vision à 6 mois ? Quelles sont les limites actuelles (ce qu’on a décidé de ne pas faire) ?
   • Pourquoi c’est crucial : Sans elle, un dev qui itère sur la feature 1 an plus tard risque de supprimer un comportement “bizarre” qui était en fait une réponse vitale à un besoin client.
   • Le public : Elle est le pont entre la Tech, le Produit et le Marketing. C’est la doc qui aligne tout le monde.
2. ROI Élevé : La Doc d’Intention (l’histoire).
   • Pourquoi ce choix ? Quelles étaient les limitations ? C’est ce qui survit aux refactos (ex: les ADR - Architecture Decision Records). N’importe quel dev peut comprendre votre code, mais personne ne peut deviner une intention métier disparue.
3. ROI Opérationnel : La Doc d’Usage (le manuel). Le strict nécessaire pour être autonome. Par exemple le guide du “Day One”. Si je ne peux pas lancer le projet à tous les coups en quelques minutes lors d’un onboarding, le README a échoué.
4. ROI Négatif : La Doc d’Implémentation. Les détails techniques changeants. C’est du “Waste”. À supprimer au profit d’un code propre, typé et bien nommé.

La documentation est écrite pour être lue, sinon elle est nulle. Une bonne documentation doit être compréhensible par la majorité de l’équipe (Tech, Produit, voire Marketing).
Le vrai danger lors d’une passation, ce n’est pas la perte du “savoir-faire” technique, c’est la disparition de la compréhension du système.