N’importe qui ayant déjà écrit de la documentation sait que le principal problème, c’est qu’elle devient rapidement obsolète une fois écrite.
Voir la publication originale
Cette dernière est republiée ici afin de ne pas dépendre entièrement d'une plateforme tierce.
Il n’y a qu’à parcourir les README des projets sur lesquels vous travaillez pour probablement y trouver des informations qui ne correspondent plus à la réalité du projet. Il y également fort à parier que vous ayez déjà vu des schémas d’architecture qui décrivent un système qui n’existe plus. Ou alors des procédures d’installation qui échouent, car plus à jour.
Pour éviter ces décalages, il est intéressant de créer une documentation capable de vivre et d’évoluer avec le projet. C’est le concept de “Living Documentation”. L’idée est simple: plutôt que de maintenir manuellement des documents décorrélés du code, la documentation est directement générée à partir de ce dernier.
C’est moins compliqué qu’il n’y paraît, et vous avez probablement les premières briques nécessaires à sa mise en place. Les tests peuvent décrire les spécifications implémentées. Des annotations peuvent servir à générer de la documentation technique. Les diagrammes d’architecture peuvent être générés à partir de l’analyse du code source. Il est possible d’automatiser énormément de choses, encore plus aujourd’hui à l’ère des IA génératives.
L’approche de “Living Documentation” permet ainsi d’avoir une documentation toujours à jour, une source de vérité fiable au cours du temps. Pour y parvenir, il est essentiel que la gestion de la documentation soit intégrée dans le processus de développement, que cela fasse partie de la culture d’équipe.
Une documentation qui ne suit pas le rythme du code est vouée à mourir. Investir dans une documentation vivante, c’est s’assurer de sa pérennité et d’améliorer durablement la maintenabilité de vos projets.
