Mental Model #3 - La documentation est un actif (quand elle n’est pas un poison)
Du "Théâtre de la documentation" à la clarté d'intention : comment arrêter de polluer vos projets avec du bruit visuel.
La documentation est un sujet ingrat.
On sait qu’il en faut, mais personne n’aime l’écrire, et encore moins la maintenir. On finit souvent par produire du contenu par culpabilité plutôt que par stratégie.
En préparant ma passation dans mon entreprise actuelle, j’ai dû me confronter à mes propres certitudes. J’ai réalisé que beaucoup d’équipes tombent dans les mêmes pièges. Voici ce que j’ai appris sur l’art de transmettre du savoir technique sans gaspiller son temps.
Le README “Cimetière”
Je me souviens d’un projet où je suis arrivé avec l’enthousiasme du premier jour. Devant moi, un README monstrueux de plus de 500 lignes. Impressionnant ? Non. Un piège.
On y trouvait des schémas d’architecture complexes, des descriptifs de modèles ultra-détaillés, une liste de endpoints et beaucoup de commandes. Le problème ? Rien n’était à jour. Les modèles ou endpoints ne correspondaient plus au code et surtout : il était impossible de lancer le projet en local car il manquait l’étape cruciale du setup des secrets.
Ce README n'était plus un outil, c'était un poids mort. C'est le cas d'école du ROI négatif :
l'équipe a passé des heures à écrire des détails d'implémentation, mais elle a échoué sur la seule chose qui compte pour un README : permettre de lancer le projet.
L'illusion du travail bien fait : Le "Theater of Documentation"
Beaucoup d’équipes pratiquent ce que j’appelle le théâtre de la documentation. On configure des générateurs de documentation illisibles et on impose des docstrings bateaux sur chaque fonction :
/** @param {string} name - The name of the user */ e
C’est une perte de temps pure. Si un script peut écrire votre doc, un humain n’a pas besoin de la lire. C’est du bruit visuel qui augmente la charge cognitive sans apporter de valeur. C’est une décharge de responsabilité : “Le code est documenté, donc j’ai fait mon job”.
Le principe est simple : le code propre (noms, types) documente l’implémentation. La documentation pertinente, elle, dit ce que le code ne peut pas dire.
L’Outdate Trap : Pourquoi votre doc périme trop vite
Le piège est simple : plus une documentation est collée à l’implémentation (le “comment”), plus son espérance de vie est courte.
Si vous documentez le fonctionnement interne d’une classe, vous écrivez une doc qui meurt à la prochaine Pull Request.
Une mauvaise documentation est pire que pas de documentation du tout : elle devient une source de désinformation.
Le modèle mental : L'asymétrie de la connaissance
En ingénierie, il existe une asymétrie brutale : écrire du code est plus facile que de le lire. Documenter l’implémentation ne fait qu’ajouter du bruit à un signal déjà complexe.
Pour qu’une documentation soit un actif, elle doit réduire la charge cognitive. Elle ne doit pas décrire le “Quoi” (le code le fait très bien), mais combler le vide sur le “Pourquoi”.
La cadre de décision ROI :
ROI = (Lectures × Temps gagné) - (Temps d’écriture + Maintenance).
Pour maximiser ce ROI, il faut distinguer quatre types de documentation :
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.
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.
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é.
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é.
Écrire pour être lu
Une documentation est un produit. Si vous avez zéro vue sur votre page Notion ou Confluence, c’est un feedback : votre investissement est nul.
Une bonne documentation doit être compréhensible par la majorité de l’équipe (Tech, Produit, voire Marketing). Si elle est trop technique, c’est que vous êtes probablement en train de documenter l’implémentation au lieu de la vision.
Le code est temporaire.
Le savoir transmis est permanent.
Ce qu’il faut vraiment transmettre : L’héritage de valeur
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. N’importe quel développeur peut lire votre code et comprendre sa syntaxe. Mais personne, même le meilleur ingénieur du monde, ne peut deviner les subtilités métier et les contraintes d’usage qui ne sont pas écrites dans le code.
Transmettre, c’est documenter les trois piliers qui prennent le plus de temps à assimiler :
La Maîtrise Fonctionnelle : Comment la feature apporte-t-elle de la valeur ? Quels sont les cas limites critiques pour le client ? Sans cette trace, un dev risque de supprimer une logique “bizarre” qui était en fait une réponse vitale à un besoin métier complexe. C’est ici que réside la vraie valeur du produit.
L’Archéologie de l’Intention : Pourquoi ces choix ? Documenter les chemins non pris (ex: “Nous n’avons pas utilisé cette API car elle ne gérait pas tel cas spécifique”) évite à votre successeur de perdre trois jours à refaire la même erreur. Documenter les trade-offs assumés permet de savoir où le code peut être amélioré et où il doit rester ainsi.
L’Autonomie d’Usage : Un projet que l’on ne peut pas lancer est un projet mort. Transmettre les secrets de l’infrastructure, les dépendances cachées et les process de déploiement, c’est garantir que le système continue de tourner sans vous.
Si cet article t’a plu je partage ici ce que j’apprends au quotidien sur le métier d’ingénieur logiciel :
Modèles mentaux d’ingénierie logiciel
Réflexion produit
Si ces sujets t’intéressent, tu peux t’abonner pour recevoir les prochains articles directement par email.