Documentation

Comment rédiger une vraie bonne documentation technique ?

Découvrez comment rédiger une documentation technique claire, utile et maintenable pour éviter la dette technique et les erreurs coûteuses.

Faire une documentation technique de qualité nécessite-t-il beaucoup (trop) de travail ? Réfléchissez-y bien. Êtes-vous plus souvent tombé sur une bonne ou une mauvaise doc technique ?

Dans bien des cas, la documentation est inexistante, obsolète, dispersée ou mal placée. En conséquence : perte de temps, perte de connaissance, perte de crédibilité. Pourtant, la documentation technique est un indispensable qui retrace les décisions techniques, les règles de sécurité appliquées, les choix d’architecture et qui sert de référence historique pour les vérifications, les audits ou les évolutions futures du système.

Mais pourquoi les documentations techniques sont-elles parfois mal faites ?

Rédiger une documentation utile et exploitable demande du temps, de la concentration et de la rigueur. Ce travail pourtant capital, n'est pas toujours valorisé par les managers, ce qui amène les développeurs, pressés par les délais, à devoir se contenter de notes rapides pour eux-mêmes ou pour cocher une case qualité exigée. La doc est alors créée de façon éparse, avec des oublis, dans un coin de git ou de Confluence, à travers des commentaires vagues sur deux fonctions dans le code avant de passer à autre chose.

C’est ainsi que naît la dette technique, avec des pertes de temps, des risques sécurité et des coûts de maintenance qui explosent.

"La dette technique liée à une mauvaise documentation" Source : Technical Debt: From Metaphor to Theory and Practice, By Philippe Kruchten, Robert Nord, and Ipek Ozkaya

Qu'est-ce-qu'une "bonne" documentation technique ?

La documentation technique est un langage naturel, conçu par les humains pour les humains, avec un cycle de vie propre et des équipes tournantes. Au moment de sa rédaction, vous devez considérer que vous ne connaissez ni le bagage technique ni le background de la future équipe qui reprendra le projet. Une bonne documentation consiste donc à écrire avec un effort d’empathie.

Une bonne documentation doit :

• Faciliter l’intégration des nouveaux développeurs,
• Expliquer les choix techniques,
• Permettre une maintenance fluide sans enquêtes interminables,
• Éviter de noyer l'essentiel dans les détails inutiles.

Quels sont les critères et contenus essentiels à placer dans une documentation technique ?

Pour la rendre efficace, une documentation doit avoir le bon niveau d'informations : ni trop, au risque de noyer l'essentiel dans du superflu, ni pas assez, au risque d'omettre des détails clés. Trois critères sont à considérer avec attention :

• La documentation doit exister réellement : un point qui paraît évident, mais qui ne l’est pas du tout dans la vraie vie : beaucoup de “docs techniques” existent uniquement sur le papier (ou dans un dépôt oublié), et ne sont en réalité ni à jour, ni utilisables, ni testées. Bref : elles n’existent pas vraiment.
• Elle doit être immédiatement trouvable : si un nouveau développeur ou un admin arrive, il ne doit pas passer une heure à chercher où est la documentation.
• Elle doit être compréhensible en quelques instants : savoir quoi faire et comment avancer. En quelques instants, on doit saisir le but, le contexte et la marche à suivre.

En parallèle, la documentation doit intégrer, à minima, trois types de contenus :

• Une vision d’ensemble (architecture, modules, décisions majeures).
• Les instructions de base (installation, build, tests, déploiement).
• Les raisons derrière les choix techniques (justification des fonctions, séparation des micro-services, etc.).

Nous insisterons dans cette partie sur ce dernier point clé : une documentation doit toujours être mise à jour car une documentation obsolète est pire qu’une documentation absente.

Où placer sa documentation technique ?

La documentation doit aller à l'essentiel, à travers plusieurs niveaux, du plus proche du code au plus global. La documentation s'écrit :

• Au sein même du code : dans les commentaires, pour permettre d'une part au développeur auteur du code de retrouver son raisonnement même deux ans plus tard ; d'autre part de faciliter la compréhension pour autres développeurs.

• le README de chaque composant : pour expliquer les contraintes, fonctionnalités et design propres à chaque composant. Quand cela approprié, vous pouvez également transmettre son lien dans les commentaires du code.

• Le README du projet : il reste la porte d’entrée idéale car il est lisible, versionné, visible et facilement accessible. Il peut contenir une table des matières cliquable renvoyant vers un wiki ou autres outils. Près de lui peut se trouver un fichier CONTRIBUTING.md préparé par les lead dev avec les process de gestion du code, des index, des scripts d’installation ou de déploiement.

Pour les projets complexes, il est possible de placer une partie de la documentation dans un wiki pour expliquer l'architecture globale et explications de concepts de plus haut niveau.

Bref : la documentation doit être là où les développeurs vivent.

IA et documentation technique : risques et exceptions

Il peut y avoir quelques usages valides pour produire de la documentation technique avec l'aide d'une IA mais de manière générale, notre recommandation est de vous déconseiller d'utiliser une IA pour faire une documentation technique.

Les limites des IA pour la documentation

Bien sûr, dans certains domaines très spécialisés, l’usage d’une IA est pertinent. Par exemple en médecine, certaines IA sont conçues uniquement pour l’analyse d’images ou la détection de signaux faibles, avec des bases de données validées, des contrôles qualité stricts et une traçabilité claire. Là, l’IA remplit un rôle précis et mesurable.

Mais ce contexte n’a rien à voir avec celui d’un développeur qui s’appuie sur une IA généraliste comme GitHub Copilot ou Codex pour rédiger ou générer de la documentation. Ces outils posent plusieurs problèmes :

• Opacité des sources, qualité discutable : Copilot ou Codex génèrent du texte à partir de modèles entraînés sur d’immenses corpus dont on ignore la provenance exacte. Le développeur n’a aucune garantie que ce qui est produit est correct, complet ou même licite d’un point de vue juridique.
• Inexactitudes, réponses sous-optimales, voire non-sens : sans lui fournir suffisamment de contexte, les réponses d'une IA risquent de négliger certains aspects du projet, en inventant ou en introduisant des erreurs. Et justement : plus vous donnez de contexte, plus vous donnez de données.
• Absence de responsabilité : contrairement à un framework ou une librairie open source versionnée, une IA ne fournit ni changelog ni traçabilité. Impossible de savoir pourquoi elle a produit tel paragraphe ou d’en vérifier la logique.
• Confusion entre “plausible” et “vrai” : ces IA génèrent du texte qui a l’air crédible, mais qui peut contenir des erreurs grossières ou des simplifications dangereuses. Une documentation trompeuse est bien plus nocive qu’une documentation absente.
• Risque de fuite : en transmettant du code ou des informations internes à un outil externe (Copilot, Codex), vous exposez potentiellement vos données propriétaires à des serveurs distants. Même si l’éditeur promet le contraire, vous perdez le contrôle.
• Propriété intellectuelle : certaines parties de texte généré peuvent dériver de dépôts publics soumis à licence. Rien ne garantit que l’extrait proposé par Copilot soit libre de droits pour votre entreprise. En cas de litige, la responsabilité retombe sur vous et spoiler, des chercheurs en sécurité pourraient facilement remonter le fil de votre code.
• Confidentialité menacée : transmettre du code à une IA en ligne expose vos données et vous ne devez en aucun cas lui transmettre votre dépôt en production sur une IA en ligne, sauf si vous tenez à ce que vos secrets industriels atterrissent dans les logs d’un LLM hébergé on ne sait où.

Rappelez-vous que la documentation technique est là pour répondre à un besoin technique humain, faite par des humains au service d'autres êtres humains. Utiliser Copilot ou Codex pour écrire une documentation technique revient alors à déléguer la mémoire critique de votre projet à une boîte noire dont vous ne maîtrisez ni les entrées, ni les sorties.

Les rares cas où une IA peut aider

La documentation technique doit rester une tâche humaine mais il existe quelques situations très spécifiques où l’IA peut avoir un rôle ponctuel, à condition de ne pas lui confier les clés du projet :

• Générer automatiquement des commentaires de fonctions.
• Produire des templates de documentation.
• Utiliser un IDE (Environnement de développement ou integrated development environment = un éditeur de texte amélioré + une suite d'outils pour builder) intégrant l’IA (comme Cursor) pour absorber le contexte du projet.

Mais même dans ces cas : la documentation technique par une IA doit systématiquement être accompagnée d'une relecture humaine. C’est une règle absolue. Sinon, en un clic, en une merge request, votre crédibilité risque d'en être entachée.

Bonnes pratiques pour rédiger une documentation technique solide

Encore une fois, le but n’est pas d’écrire une encyclopédie indigeste mais de produire une documentation utile, légère, à jour :

Intégrer la documentation dès le début du projet

La doc n’est pas une tâche de fin de cycle et vous ne devez pas l'écrire à la fin. Considérée comme la porte d'entrée du projet, elle vit et évolue avec le code, dans des formats adaptés (Markdown, HTML, wiki).

Des commentaires utiles et clairs dans le code

Pour expliquer ce qui vous parait peut-être l’évidence mais pas à ceux qui reprendront le projet, privilégier les explications claires et justifiées plutôt que le remplissage inutile.

Versionner et relire la documentation

La doc doit évoluer dans le dépôt, être relue à chaque pull request et toute nouvelle fonctionnalité doit s’accompagner de sa mise à jour documentaire. La documentation évolue. Il faut pouvoir revenir en arrière, comprendre quand et pourquoi certains choix ont été faits en adoptant un outil de versioning comme Git.

Désigner des responsables et s’appuyer sur des standards

Attribuer la responsabilité de la documentation à un membre de l'équipe, avec, à chaque sprint, un référent en charge de tenir à jour un historique clair (avec les anciennes versions pour consultation ou justification réglementaire). Cela permet d'améliorer largement la rigueur de la documentation. Également, s’appuyer sur des standards éprouvés permet d’assurer sa cohérence et pérennité. Quelques exemples de cadres adaptés pour l'industrie :

• Modèle C4 : pour une visualisation hiérarchique claire de l’architecture logicielle.
• Arc42 : pour structurer la documentation technique de manière modulaire pour l'architecture du système.
• UML : des diagrammes pour des schémas de conception standardisés, modélisation des systèmes.
• ISO/IEC 42010 : une norme pour une description normalisée des architectures.

Conclusion

Une documentation technique n’est pas une contrainte administrative mais un levier stratégique. Elle doit être pensée pour les autres, placée au bon endroit et tenue à jour avec rigueur. Tout le reste est de la dette technique en embuscade.