Rendre la documentation utile et accessible grâce à l’IA

TL;DR

Une documentation n’est réellement utile que si elle répond aux questions au moment où elles se posent. Pour résoudre le problème de la documentation peu consultée, j’ai développé un serveur basé sur le protocole MCP (Model Context Protocol) qui rend notre documentation interne interrogeable en langage naturel directement dans l’IDE. Résultat : l’accès devient fluide, l’usage augmente, et l’envie de documenter revient. Projet open‑source, conçu pour améliorer l’expérience développeur et la qualité logicielle.

Introduction

Dans le développement logiciel, la documentation joue un rôle essentiel : transmettre le savoir, harmoniser les pratiques, faciliter l’arrivée de nouveaux développeurs et assurer la maintenance à long terme. Pourtant, dans la réalité du terrain, elle reste souvent sous‑consultée.

Dans mon équipe, nous avions tout bien fait : une documentation centralisée dans un dépôt Git, versionnée, structurée, et publiée automatiquement sous forme de site statique. Mais un problème persistait : au moment où l’on en avait réellement besoin, elle n’était jamais là.

Ce constat a lancé une réflexion simple : et si la documentation pouvait venir à nous, plutôt que l’inverse ?

Cette idée a donné naissance à une expérimentation : intégrer l’intelligence artificielle pour rendre la documentation accessible directement dans l’IDE.

Un paradoxe récurrent

Nous n’en produisions plus autant qu’au lancement de notre démarche documentaire. Après un premier élan, l’écriture et les mises à jour avaient progressivement diminué, concurrencées par les assistants de code de plus en plus performants… mais qui, eux, ne disposent d’aucun contexte interne au projet.

Quand une bonne pratique est oubliée et qu’un bug apparaît, il est déjà trop tard pour aller relire la documentation. Pire encore : produire un document sans qu’il soit réellement utilisé démotive ceux qui l’écrivent.

La documentation ne sert que si elle est consultée au bon moment, c’est‑à‑dire quand une question se pose.

L’objectif est donc devenu évident :

La documentation doit accompagner l’écriture du code, pas la suivre.

Ouvrir la voie : l’IA au service du flux de travail

Nous utilisons déjà des assistants de code pour générer des tests, proposer des améliorations ou guider le TDD. Pourquoi ne seraient‑ils pas capables de répondre à des questions sur les conventions internes, les règles métier ou les guidelines projet ?

Nous avons imaginé une documentation interrogeable comme un collègue :

• sans naviguer dans des dossiers
• sans changer d’application
• sans interrompre notre concentration

Si la réponse à notre question arrive directement dans l’IDE, alors la documentation redevient un outil réellement utile.

La solution : un serveur MCP connecté à S3

Pour répondre à ce besoin, j’ai développé un serveur MCP (Model Context Protocol) qui permet d’interroger notre documentation interne, en langage naturel, directement dans l’environnement de développement.

La mécanique derrière cela reste pourtant très simple : la documentation continue d’être écrite dans Git, mais plutôt que de la consulter directement depuis un dépôt, une étape CI/CD la synchronise automatiquement vers S3, où elle devient accessible par le serveur.

Pourquoi passer par S3 plutôt que Git directement ?

Ce choix offre deux avantages importants :

• Une source indépendante du dépôt Git Cela ouvre la voie à d’autres origines documentaires : stockage S3 compatible, CMS, exports automatisés… sans changer le fonctionnement interne du serveur MCP.

• Une contribution accessible à tous les profils Avec un simple script ou une petite étape CI/CD, n’importe qui peut publier du contenu Markdown sur S3, même sans accès direct au repository ou sans connaître Git.

En résumé : Git reste le lieu naturel d’écriture, S3 devient la porte d’entrée universelle vers la documentation exploitable par notre serveur MCP.

Le serveur indexe ensuite les contenus synchronisés et les met à disposition via une recherche sémantique, permettant une consultation fluide directement dans l’IDE.

Requêtes naturelles dans l’IDE

Concrètement, comment cela fonctionne-t-il ? Le protocole MCP donne accès à un système RAG (Retrieval-Augmented Generation) qui permet de poser des questions telles que :

« Quelles sont nos règles internes pour écrire des tests unitaires ? »

Le serveur retourne un extrait pertinent et un lien direct vers la source Markdown. Pas besoin de quitter le fichier sur lequel on travaille.

Une recherche sémantique, pas un simple grep

Contrairement à une recherche textuelle classique qui cherche des mots-clés exacts, le serveur utilise le concept de RAG (Retrieval-Augmented Generation). Il convertit les fichiers Markdown en embeddings vectoriels et garde cet index à jour. Cette approche lui permet de comprendre le sens de la question et de proposer les contenus les plus adaptés, même si les termes utilisés dans la question diffèrent de ceux du document.

RAG en pratique : Le système combine deux étapes : d’abord, il recherche dans la base de connaissances les documents les plus pertinents (Retrieval), puis il utilise ces informations pour générer une réponse contextuelle (Augmented Generation). C’est ce qui permet de répondre précisément aux questions tout en s’appuyant sur la documentation existante.

Par exemple, une question sur “comment tester mes fonctions” trouvera automatiquement un document qui parle de “tests unitaires” ou de “validation de code”, même sans correspondance textuelle exacte.

Un accès complet aux ressources internes

Ce serveur MCP expose des tools et des ressources au sens du protocole MCP : chaque document de documentation devient une ressource accessible via une URI unique.

Le serveur implémente deux types d’accès :

MCP Tools (outils d’action) :

• search_documentation : recherche sémantique dans la documentation
• refresh_index : synchronisation de l’index avec S3
• get_full_document : récupération d’un document complet

MCP Resources (ressources de données) :

• resources/list : liste tous les fichiers indexés avec métadonnées
• resources/read : accès direct au contenu d’un fichier via son URI

Ressources MCP en pratique : Chaque ressource est identifiée par une URI unique (comme s3doc://docs/guide-testing.md), contient des métadonnées (nom, description, type MIME) et peut être lue par le client MCP. L’IA peut ainsi accéder directement aux documents, naviguer dans leur structure, et les utiliser comme contexte pour générer des réponses précises.

Cette approche permet à l’IA de revenir à la source, naviguer dans les sections utiles ou reformuler plus précisément selon le besoin. L’assistant peut ainsi fournir des réponses nuancées, citer les bonnes sections, et même suggérer des documents complémentaires.

Un projet open‑source

Ce serveur, baptisé S3 Documentation MCP Server, est disponible publiquement :

• Code source : https://github.com/yoanbernabeu/S3-Documentation-MCP-Server
• Documentation : https://yoanbernabeu.github.io/S3-Documentation-MCP-Server/

Note sur le code : Ce projet a été développé selon nos besoins spécifiques et évolue en permanence. Le code est ce qu’il est, pas le meilleur du monde, mais fait avec amour (et Cursor !). Il continuera d’évoluer selon les besoins observés en production et les retours de la communauté.

Premiers retours du terrain

L’intégration est encore récente, mais plusieurs constats se dégagent. Pendant longtemps, l’usage de la documentation n’incitait pas à en produire davantage. Après un premier élan collectif, les contributions avaient fini par diminuer : pourquoi enrichir un contenu qui ne sert pas vraiment au quotidien ?

Puis, avec l’arrivée du serveur MCP, quelque chose a changé : celles et ceux qui ont commencé à l’utiliser se sont remis à documenter. Parce que leurs apports étaient immédiatement utiles. Parce que la documentation redevenait une ressource vivante, consultée, valorisée.

Plusieurs constats se dégagent désormais :

• L’outil suscite beaucoup de curiosité dans l’équipe
• Chacun perçoit son potentiel, notamment pour l’onboarding

À titre personnel, le changement est déjà majeur : je ne vais plus “voir” la documentation. Ce sont mes questions qui y accèdent. Et cela change profondément mon flux de développement.

Une IA pragmatique

Cette démarche n’a pas pour ambition de remplacer l’humain ni son expertise, mais de rendre celle‑ci plus facilement mobilisable.

Concrètement, cette approche :

• réduit le temps passé à chercher l’information
• renforce l’application des bonnes pratiques
• améliore le confort et la concentration du développeur

Ici, l’IA n’écrit pas le code. Elle rend les développeurs plus efficaces.

Enseignements

Une petite évolution, bien appliquée, peut modifier durablement les habitudes d’une équipe.

Ce projet montre que :

• la documentation n’a de valeur que si elle est accessible au moment utile
• mieux exploiter l’existant vaut mieux qu’introduire un nouvel outil
• l’expérience développeur n’est jamais un luxe

Ce n’est pas la documentation qui change. C’est la manière de l’utiliser.

Suite du projet

Nous commencerons à mesurer l’impact réel dans les prochaines semaines :

• fréquence d’accès aux contenus
• amélioration de la cohérence entre projets
• rapidité dans l’application des standards

D’autres fonctionnalités viendront enrichir le serveur, selon les besoins rencontrés.

Je partagerai ces résultats dès que nous aurons du recul.

Conclusion

Ce projet propose une nouvelle vision de la documentation :

un outil intégré au flux de développement, présent au moment où l’on en a besoin.

Même documentation. Nouvelle accessibilité. Valeur décuplée.

En rendant la documentation plus vivante, on renforce la qualité logicielle sans alourdir le quotidien des développeurs.

Et si une simple expérimentation peut améliorer durablement notre manière de travailler… alors elle mérite d’être poussée plus loin.