Documentation-as-Code : documentation technique synchronisée avec les versions
Comment la documentation comme code aide à garder la documentation technique du règlement sur l'IA en phase avec chaque changement du code.
Points essentiels
- 1.Les fournisseurs de systèmes d'IA à haut risque doivent tenir leur documentation technique à jour (article 11, paragraphe 1).
- 2.La documentation comme code conserve la documentation technique sous gestion de versions, à côté du code.
- 3.Certaines parties peuvent être générées à partir du code et des données du pipeline. Les décisions qui demandent du jugement exigent des personnes.
- 4.La gestion de versions montre ce qui a changé et quand, pas que le contenu est correct.
L'obligation s'applique aux fournisseurs de systèmes d'IA à haut risque. Elle vise ceux qui les mettent sur le marché de l'UE ou les y mettent en service, selon l'article 2, paragraphe 1, point a). L'annexe IV liste ce que la documentation doit contenir. L'annexe III est la liste des usages à haut risque du règlement, comme le recrutement. L'annexe I concerne l'IA intégrée à des produits soumis au droit de sécurité de l'UE. La section A de l'annexe I liste des textes sur les produits, par exemple sur les jouets et les dispositifs médicaux. La section B liste d'autres textes sur les produits. Pour les systèmes de l'annexe III, l'obligation s'applique à partir du 2 décembre 2027. Pour les systèmes de la section A de l'annexe I, elle s'applique à partir du 2 août 2028 (règlement (UE) 2026/1744). Les systèmes mis sur le marché ou mis en service avant ces dates relèvent de l'article 111, paragraphe 2. Ce paragraphe a été remplacé par le règlement (UE) 2026/1744. Hors les systèmes de l'article 111, paragraphe 1, ils ne sont couverts que si, dès la date applicable, leur conception subit des modifications importantes. Pour les systèmes destinés aux autorités publiques, l'article 111, paragraphe 2, exige les mesures nécessaires à la conformité d'ici le 2 août 2030.
Pour les systèmes à haut risque liés à des produits de la section B de l'annexe I, l'article 2, paragraphe 2, limite les dispositions applicables. Seuls s'appliquent l'article 6, paragraphe 1 (règles de classification), et les articles 102 à 112 (dispositions finales). S'applique aussi l'article 60a (essais en conditions réelles hors bacs à sable). Les articles 57 à 59 portent sur les bacs à sable réglementaires de l'IA. Ils ne s'appliquent que dans la mesure où ces textes intègrent les exigences du règlement pour l'IA à haut risque. L'article 11 n'y figure pas.
Les obligations du fournisseur figurent à l'article 16. Une violation peut coûter jusqu'à 15 millions d'EUR ou, pour une entreprise, 3 % du chiffre d'affaires annuel mondial (article 99, paragraphe 4). Le montant le plus élevé s'applique. Pour les microentreprises et les petites et moyennes entreprises (PME, article 3, point 14a), le montant le plus bas s'applique (article 99, paragraphe 6).
Avec la documentation comme code, les changements sont relus dans des pull requests et chaque version est associée à une release. Première étape : vérifiez, avec le tableau ci-dessous, lesquels des neuf points de l'annexe IV vous pouvez générer à partir de votre dépôt.
Pourquoi les documents hors du dépôt dérivent
Les documents dans des fichiers Word, des PDF ou des wikis sont séparés du code qu'ils décrivent.
Un document peut décrire une ancienne version
La mise à jour se fait à la main
Ce que signifie la documentation comme code en pratique
La documentation comme code applique à la documentation technique les pratiques de l'ingénierie logicielle :
Gestion de versions
La documentation technique se trouve dans le même dépôt Git que le code. Chaque modification est un commit avec un auteur, une date et un diff, ce qui permet de relier une version du document à une version du code.
Génération quand c'est possible
Certaines sections peuvent être générées à partir de la base de code, comme le montre le tableau ci-dessous. Les sections qui demandent du jugement sont écrites par des personnes.
Contrôles dans le pipeline
Votre équipe peut écrire une règle de pipeline qui fait échouer une pull request quand le modèle change sans que la section de document correspondante change. Le règlement ne l'exige pas.
Paquets de release
Chaque release regroupe les documents avec la version du logiciel : vous pouvez ainsi produire la documentation qui correspondait à une release donnée.
La génération aide davantage pour certains points de l'annexe IV que pour d'autres
La génération aide un peu pour 4 des 9 points de l'annexe IV, peu pour 4 et pas du tout pour 1. Les deux colonnes de droite sont notre appréciation, pas celle du règlement.
Les PME et les petites entreprises à moyenne capitalisation (SMC, article 3, point 14b) peuvent fournir les éléments de l'annexe IV de manière simplifiée. Cela découle de l'article 11, paragraphe 1, tel que modifié par le règlement (UE) 2026/1744. Celles qui le font doivent utiliser le formulaire simplifié que la Commission doit établir. Le montant d'amende le plus bas s'applique aussi aux SMC (article 99, paragraphe 6a).
| Point de l'annexe IV | Approche possible | Aide de la génération |
|---|---|---|
| 1. Description générale du système d'IA | Noms et versions tirés du manifeste, du README et des métadonnées de release | En partie |
| 2. Éléments du système et de son processus de développement | Descriptions d'architecture et de pipeline tirées du code ; justification de la conception rédigée par des personnes | En partie |
| 3. Surveillance, fonctionnement et contrôle | Chiffres d'exactitude tirés des résultats de tests ; limites et mesures de contrôle humain rédigées par des personnes | En partie |
| 4. Adéquation des indicateurs de performance | Indicateurs tirés des pipelines d'évaluation ; l'argumentation sur leur adéquation est rédigée par des personnes | Peu |
| 5. Système de gestion des risques (article 9) | Registre des risques sous forme de fichier versionné ; l'analyse des risques est faite par des personnes | Peu |
| 6. Modifications pertinentes tout au long du cycle de vie | L'historique Git et le journal des modifications donnent la liste brute ; le fournisseur choisit les modifications pertinentes | En partie |
| 7. Normes appliquées | Une liste tenue à jour dans le dépôt | Peu |
| 8. Copie de la déclaration UE de conformité | La déclaration signée, conservée avec la release | Aucune |
| 9. Système de surveillance après commercialisation (article 72) | Le plan sous forme de document versionné ; les données de surveillance viennent de l'exploitation | Peu |
Exemple d'organisation : des fichiers de documentation à côté du code
Cette organisation est un exemple, pas une structure imposée.
your-ai-system/
├── src/
├── docs/
│ └── compliance/
│ ├── annex-iv/
│ │ ├── 01-general-description.md
│ │ ├── 02-development-process.md
│ │ └── ...
│ ├── risk-register.yaml
│ └── oversight.md
├── tests/
│ └── docs/
└── .github/
└── workflows/
└── docs-check.ymlUn pipeline peut vérifier les documents à chaque pull request
Analyser : examiner la base de code
Une étape d'analyse peut utiliser un outil qui détecte dans le code les motifs courants des frameworks de ML. Les wrappers sur mesure et le code obscurci peuvent échapper à la détection.
Générer : actualiser les projets
Le pipeline reconstruit les sections générées à partir des entrées actuelles : le diff montre donc ce qui a changé dans les documents.
Valider : vérifier la complétude
Des règles vérifient que les sections requises existent et contiennent le contenu requis. Un contrôle du contenu n'est pas un contrôle de véracité : des personnes relisent l'exactitude.
Rapporter : afficher le résultat sur la pull request
La pull request indique quels contrôles ont réussi ou échoué : un relecteur voit ainsi l'effet sur la documentation avant la fusion du changement.
Le texte brut permet une relecture ligne par ligne, et la protection de branche garde l'historique
Les pull requests montrent les lignes modifiées
Protéger l'historique
Articles connexes
Sources et références
- Regulation (EU) 2024/1689 (EU AI Act) — articles 2, 3, 11, 16, 43 et 99 et annexes I, III et IV (annexe IV : neuf points de documentation technique).
- Regulation (EU) 2026/1744 — Digital Omnibus on AI — dates d'application (article 113) et modifications des articles 2, paragraphe 2, 3, 11, paragraphe 1, 99 et 111, paragraphe 2, et le nouvel article 60a.
- GitHub Docs — About protected branches — les règles de protection de branche déterminent si les collaborateurs peuvent faire un force push sur une branche.
- Pro Git — Viewing the Commit History — l'historique des commits liste chaque commit avec son auteur, sa date et son message ; avec l'option de patch, il montre le diff.
Questions fréquemment posées
Qu'est-ce que la documentation comme code pour la documentation du règlement sur l'IA ?
La documentation comme code conserve la documentation technique sous gestion de versions, la modifie par des pull requests et en génère certaines parties dans un pipeline. Le but est que la documentation technique corresponde au système tel qu'il a été publié.
Pourquoi les documents hors du dépôt dérivent-ils ?
Les fichiers Word et les PDF sont séparés du code : un changement du code ne les met donc pas à jour. Quelqu'un doit les mettre à jour, car l'article 11, paragraphe 1, exige que la documentation technique soit tenue à jour.
La documentation comme code satisfait-elle l'annexe IV ?
Aucune pratique ne satisfait l'annexe IV à elle seule. L'annexe IV fixe le contenu en neuf points. La documentation comme code aide à garder ce contenu à jour et traçable. Le fournisseur doit veiller à ce que le système respecte les exigences du chapitre III, section 2, dont l'article 11 (article 16, point a)).
Quels outils utilise-t-on pour la documentation comme code ?
Vous pouvez combiner Git, des fichiers Markdown ou YAML et un pipeline CI pour les contrôles et la génération. Un scanner ou un générateur peut produire les sections déduites du code.
À quelle fréquence faut-il mettre à jour la documentation technique d'un système d'IA ?
L'article 11, paragraphe 1, exige que la documentation technique soit établie avant la mise sur le marché ou la mise en service du système, et tenue à jour. L'article 11, paragraphe 1, ne fixe aucun intervalle. Nous suggérons de la relire à chaque release et après tout changement du modèle, des données d'entraînement ou de la finalité prévue. Une modification substantielle exige une nouvelle évaluation de la conformité (article 43, paragraphe 4). Une modification substantielle est un changement postérieur à la mise sur le marché ou à la mise en service. La première évaluation de la conformité ne l'avait ni prévu ni planifié. Elle affecte le respect des exigences applicables aux systèmes d'IA à haut risque (chapitre III, section 2) ou change la finalité prévue (article 3, point 23). Une évaluation de la conformité est la procédure qui démontre si ces exigences sont respectées (article 3, point 20).
Scanara prépare des preuves à partir de vos dépôts
Scanara lit vos dépôts GitHub connectés et exécute des analyses à base de règles pour repérer les schémas courants d'IA et d'apprentissage automatique. Il peut manquer du code non standard. Par ailleurs, il génère des projets de documentation à partir de modèles et de vos réponses aux évaluations, comme preuves pour votre travail de conformité. Vous décidez de la classification.