Une documentation de fin de projet IA est utile quand une personne compétente qui n'a pas participé au projet peut, avec elle seule, installer l'application, la faire tourner, la corriger et la mettre en production. Elle doit couvrir sept éléments : architecture, accès et secrets, procédure de mise en production, journal des décisions, jeux de tests, limites connues et plan de reprise.
Pourquoi la documentation décide-t-elle de votre autonomie ?
Un projet IA livré sans documentation fonctionne le jour de la recette et devient opaque six mois plus tard. Le prestataire change de poste, un modèle est retiré par son éditeur, une clé d'API expire, et personne ne sait plus où se trouve quoi. Vous payez alors une seconde fois pour comprendre ce que vous avez déjà acheté.
Le principe de départ est simple : le client est propriétaire du code et des accès. Ce n'est pas un détail contractuel, c'est la condition pour que la documentation ait un sens. Documenter un système qu'on ne contrôle pas revient à décrire la maison d'un autre. Chez JUWA, cabinet de conseil et de développement en IA, les dépôts, les comptes d'hébergement et les clés sont créés sous votre organisation dès le début de la mise en production de votre projet IA, pas transférés à la fin.
Prenons une PME de distribution technique de 120 salariés, avec un assistant interne qui répond aux commerciaux à partir du catalogue et des fiches produits. L'assistant marche. Mais le jour où le responsable informatique veut changer de modèle pour réduire la facture, il découvre que le prompt système est dans le code, que le catalogue est vectorisé par un script que personne n'a documenté, et que la clé d'API est liée à l'adresse personnelle d'un ancien consultant. Rien n'est cassé, tout est bloqué.
Quels éléments doit contenir une documentation de projet IA ?
Sept éléments, pas un de moins. Les trois premiers servent à comprendre, les quatre suivants à agir.
- L'architecture : un schéma des composants (interface, API, base de données, base vectorielle, modèle, tâches planifiées), les flux entre eux et ce qui sort de votre périmètre (service tiers, API d'éditeur).
- Les accès et les secrets : qui a accès à quoi, où sont stockées les clés, comment on les renouvelle.
- La procédure de mise en production : de la modification du code à sa mise en ligne, commandes comprises, avec la marche arrière.
- Le journal des décisions : pourquoi tel modèle, tel découpage des documents, telle règle de gestion.
- Les jeux de tests : questions et réponses attendues, rejouables.
- Les limites connues : ce que le système ne fait pas, ou fait mal.
- Le plan de reprise : que faire en cas de panne, de perte d'un accès, de départ d'une personne clé.
Chaque point mérite quelques lignes de détail.
Que doit-on documenter sur l'architecture ?
Un schéma lisible vaut mieux que vingt pages. Il montre les briques, le sens des flux et l'endroit où vivent les données. Pour un système de RAG, par exemple, on doit y trouver : d'où viennent les documents, comment ils sont découpés, quel modèle les transforme en vecteurs, où ils sont stockés, quel modèle génère la réponse, et quelles sources sont citées.
Ajoutez les versions : version du modèle, des bibliothèques principales, du moteur de base de données. Une application IA dépend de composants qui évoluent vite. Sans numéros de version, impossible de reproduire un comportement, ni de comprendre pourquoi une réponse a changé après une mise à jour. Le sujet du suivi après livraison est détaillé dans notre article sur ce qu'il faut surveiller après la mise en production d'une IA.
Comment documenter les accès et les secrets sans créer de faille ?
La documentation ne contient jamais les secrets eux-mêmes. Elle dit où ils sont (un gestionnaire de secrets, pas un fichier texte ni un courriel), qui peut les lire, et comment les remplacer. Un document qui contient un mot de passe est un document à protéger comme un mot de passe, donc à retirer du dépôt.
Elle liste aussi les comptes : hébergeur, fournisseur de modèles, nom de domaine, outil de supervision, messagerie utilisée pour les alertes. Pour chacun : le titulaire (votre organisation), les personnes habilitées, la date de dernière revue. Le guide d'hygiène informatique de l'ANSSI, qui rassemble 42 mesures de base pour les systèmes d'information, est une bonne référence pour la discipline générale. Dans la pratique, on en retient trois règles : des comptes nominatifs, des droits au strict nécessaire, et la fin des accès dès qu'une personne quitte le projet.
À quoi ressemble une procédure de mise en production utilisable ?
Elle se lit comme une recette de cuisine, et se teste de la même façon. Étape 1, récupérer le code. Étape 2, installer les dépendances. Étape 3, lancer les tests. Étape 4, déployer en préproduction. Étape 5, vérifier. Étape 6, passer en production. Étape 7, savoir revenir en arrière si les contrôles échouent.
Le point que l'on oublie le plus : les variables d'environnement. Une application IA en compte souvent une dizaine (clés, adresses de services, noms de modèles, seuils). La documentation doit fournir un fichier d'exemple avec leurs noms et leur rôle, sans les valeurs.
Si votre application est déjà en production sans cette procédure, c'est le premier chantier d'une reprise applicative, que nous décrivons dans comment reprendre une application sans documentation.
Pourquoi tenir un journal des décisions ?
Parce que le code dit ce qui a été fait, jamais pourquoi. Un journal des décisions tient en une page par choix : le contexte, les options écartées, la raison retenue, la date. Exemple type : un assistant est limité à 15 documents par requête. Un nouveau développeur lève la limite pour « améliorer les réponses », et la facture de jetons s'envole, puisque chaque document ajouté au contexte est facturé à chaque question. La raison de la limite (un compromis entre coût et pertinence, mesuré sur un jeu de tests) n'était écrite nulle part. Elle aurait tenu en quatre lignes. À l'inverse, un journal bien tenu sert de levier : sur le copilote livré à SuperHote, le filtrage des données envoyées au modèle a ramené l'entrée d'environ 30 000 à 1 500 jetons par requête, une décision qui doit rester tracée pour ne pas être défaite.
Ce journal est aussi votre meilleur outil pour piloter les coûts après livraison. Pour aller plus loin sur ce sujet, lisez le détail de la facture mensuelle d'un agent IA en production.
Quels jeux de tests exiger, et pourquoi sont-ils si importants ?
Un système d'IA ne se comporte pas comme un logiciel classique : une même question peut donner des réponses différentes, et un changement de modèle modifie tout. Le seul moyen de savoir si une évolution casse quelque chose est de rejouer un jeu de questions de référence et de comparer les réponses.
On attend donc, dans la livraison : un fichier de questions représentatives des vrais usages (50 à 200 selon le périmètre), les réponses ou sources attendues, un script qui les rejoue et produit un score, et le résultat de la dernière exécution. Chez JUWA, les batteries de tests par IA sont mises en place tôt dans le projet, pas ajoutées à la fin. Le client en reçoit la propriété comme le reste du code.
Comment présenter les limites connues et le plan de reprise ?
Une documentation honnête dit ce qui ne marche pas. Les limites connues tiennent en une liste courte : types de documents mal lus (scans de mauvaise qualité, tableaux complexes), langues non testées, volumes au-delà desquels les temps de réponse se dégradent, sujets sur lesquels l'assistant doit refuser de répondre. Ce n'est pas un aveu de faiblesse : c'est ce qui évite qu'un utilisateur prenne une réponse fausse pour une vérité.
Le plan de reprise répond à quatre questions. Que fait-on si le fournisseur de modèle est en panne ? Qui est prévenu, et comment ? Comment restaure-t-on la base de données ? Qui peut agir si la personne référente est absente ? Écrit à froid, calmement, il évite les décisions hâtives un vendredi soir.
Comment vérifier la documentation à la recette ?
En la faisant exécuter par quelqu'un qui n'a pas travaillé sur le projet : votre responsable informatique, un autre développeur, ou un prestataire tiers. Il reçoit la documentation et rien d'autre. On lui demande de :
- cloner le code et lancer l'application en local ;
- rejouer le jeu de tests et obtenir un score comparable à celui annoncé ;
- déployer en préproduction en suivant la procédure ;
- retrouver, sans aide, où se trouve chaque compte et qui en est titulaire ;
- expliquer, à partir du journal, pourquoi un choix structurant a été fait.
Chaque blocage devient une réserve de recette, corrigée avant la clôture du projet. La maintenance supervisée, elle, est un abonnement distinct : la documentation ne la remplace pas, mais elle vous laisse libre de la confier à JUWA ou à un autre prestataire.
Que manque-t-il le plus souvent dans les documentations reçues en reprise ?
Sur les applications reprises, la même poignée de manques revient. Le cas publié de Fit Doors en donne un exemple extrême : un code remis qui ne démarrait pas, aucun test, et 49 points de sécurité sur 51 encore ouverts. Les schémas existent, souvent, mais sont périmés. Les accès sont au nom d'une personne partie. Les variables d'environnement ne sont pas listées. Il n'y a aucun jeu de tests, donc personne n'ose toucher au prompt ou au modèle. Et les décisions n'ont laissé aucune trace.
Ces cas ressemblent à la situation décrite dans notre article sur la dépendance à un seul développeur : tant que la personne est là, tout va bien. La documentation est ce qui transforme une compétence individuelle en actif de l'entreprise. Si vous préparez un projet ou une reprise, notre équipe peut vous aider à poser ces exigences dès le cahier des charges, lors d'un échange sur votre passage en production d'une application IA.









