Documentation as code : ce que les connaissances de l’entreprise peuvent en tirer
Par Gregory Culpin
Le knowledge as code étend la documentation as code aux connaissances de l’entreprise : un responsable, une approbation et une version pour chaque changement.
Le knowledge as code consiste à gérer les connaissances de l’entreprise comme les équipes de développement gèrent leur code. Chaque article a un responsable, chaque modification est relue avant publication, chaque version est conservée, et des contrôles automatiques signalent ce qui n’est plus à jour. C’est la documentation as code, pratique bien établie pour la documentation technique, appliquée aux procédures, aux politiques internes et aux résolutions d’incidents dont dépend le reste de l’entreprise. Le but : une seule source gouvernée, lue à la fois par les collaborateurs et par les agents IA.
Dans une DSI ou une équipe data, le code est déjà géré de cette façon. Les procédures, les modes opératoires et les runbooks, beaucoup moins.
La documentation as code, une pratique déjà éprouvée
Write the Docs, la communauté internationale des professionnels de la documentation, définit la documentation as code comme le fait d’écrire la documentation avec les mêmes outils que le code : gestionnaire de tickets, gestion de versions, texte balisé simple, revue de code et tests automatiques.
En 2017, le Government Digital Service (GDS) britannique expliquait pourquoi il gère sa documentation technique de cette façon : chaque modification est tracée, toute version antérieure peut être restaurée, chacun peut proposer une correction, et l’équipe entière partage la responsabilité du contenu. Les standards d’ingénierie du Home Office, le ministère britannique de l’Intérieur, mis à jour en avril 2025, demandent d’appliquer la documentation as code partout où c’est possible. Ils citent un avantage qui vaut bien au-delà du logiciel : une équipe peut refuser d’intégrer une nouvelle fonctionnalité tant que sa documentation n’existe pas.
Ces sources parlent de documentation technique, écrite pour des développeurs. Le GDS reconnaissait d’ailleurs deux problèmes non résolus : gérer de gros volumes et retirer les contenus anciens. Ce sont précisément les deux difficultés d’une base de connaissances d’entreprise.
Pratique par pratique : du dépôt de code à la base de connaissances
Chaque pratique du développement logiciel existe pour éviter un problème précis, et ce problème se pose aussi dans une base de connaissances.
| Pratique logicielle | Équivalent côté contenus | Ce qu’elle évite |
|---|---|---|
| Un responsable par fichier ou par module | Un responsable par article, avec une passation quand il s’en va | Des articles que personne n’entretient |
| Revue avant fusion | Approbation avant publication, y compris des mises à jour | Un changement non vérifié qui arrive aux lecteurs |
| Historique des versions | Toutes les versions conservées, qui a changé quoi, retour possible | Ne plus savoir ce qui était vrai, et quand |
| Tests automatiques | Contrôles des revues en retard, des liens cassés, des articles sans responsable | Des contenus périmés sans alerte |
| Dépréciation | Archivage qui retire l’article de la recherche sans le supprimer | Appliquer une procédure abandonnée |
| Journal des changements | Une note au lecteur : ce qui a changé, et pourquoi | Travailler de mémoire sur l’ancienne version |
| Structure typée, lisible par machine | Types d’articles, modèles et métadonnées que les outils savent lire | Un agent IA incapable de distinguer un brouillon d’une réponse approuvée |
Le responsable. Le guide de Lynda Cooper, qui a dirigé la rédaction de la norme ISO/IEC 20000-1 (gestion des services), demande de recenser les sources de connaissances et de nommer un responsable pour chacune (avril 2025).
L’approbation et les versions. Le monde de la qualité connaît ces règles depuis longtemps. En 2020, la Haute Autorité de santé décrivait ainsi le cycle de vie d’un document : élaboration, validation, diffusion, durée de validité, révision régulière, suppression des versions périmées, le tout formalisé dans une "procédure des procédures". Le site du NHS britannique exige l’accord de deux membres de son équipe clinique pour tout nouveau contenu ou changement majeur.
Les tests. Un contrôle automatique repère une date de revue dépassée, un lien mort ou un article sans responsable. La méthode Knowledge-Centered Success (KCS), portée par le Consortium for Service Innovation, utilise une grille de six questions : l’article est-il unique, complet, clair, bien titré ? Ses liens sont-ils valides, ses métadonnées justes ?
L’archivage et le journal des modifications. GOV.UK distingue deux façons de retirer une page. Une page "withdrawn" reste à son adresse, avec un bandeau indiquant qu’elle n’est plus à jour, et sort de la recherche interne. Une page dépubliée disparaît et peut rediriger vers le contenu actuel. La convention Keep a Changelog rappelle, elle, qu’un journal des modifications s’adresse d’abord à des humains.
Une structure lisible par les outils. DITA 1.3, le standard de documentation approuvé par OASIS en 2015, range ses sujets principaux dans trois types : concept, tâche ou référence. Une tâche a des parties définies, dans un ordre fixe : prérequis, contexte, étapes, résultat. Dans une base de connaissances, les modèles d’articles et les métadonnées (responsable, date de revue, statut) jouent ce rôle, et les logiciels, agents IA compris, savent les lire. Les agents IA y accèdent souvent par le Model Context Protocol (MCP), que notre guide sur la gestion des connaissances pour l’IA présente en détail. Ce protocole est lui-même gouverné comme du code : chaque évolution passe par une proposition écrite, et chaque version est datée.
Où la comparaison s’arrête
La transposition est utile, mais une procédure n’est pas un programme. Trois différences changent la manière de l’appliquer.
Pas de compilateur pour les connaissances
Un code erroné ne passe en général ni la compilation ni les tests. Une procédure fausse, elle, passe inaperçue : quelqu’un la lit et l’applique. Les contrôles automatiques vérifient la forme d’un article, jamais sa justesse. Une étude sur Stack Overflow montre que 58,4 % des réponses obsolètes l’étaient sans doute dès leur publication, et que 20,5 % seulement des réponses obsolètes ont été mises à jour (IEEE Transactions on Software Engineering, 2019). KCS confie ce contrôle aux lecteurs : chaque réutilisation vaut relecture. Celui qui utilise un article le vérifie sur le moment, et le signale ou le corrige s’il est faux.
Des lecteurs pressés, des auteurs qui n’utilisent pas Git
Une procédure a de nombreux lecteurs, souvent pressés, et désormais des agents IA. Ses auteurs sont gestionnaires de paie, techniciens de terrain ou responsables qualité : ils n’ouvriront pas de pull request, et rien ne les y oblige. Ce qui se transpose, ce sont les pratiques : responsable, approbation, versions, contrôles. L’outillage, lui, reste chez les développeurs. Autre limite : une entreprise ne peut pas faire vivre deux versions d’une même procédure comme on maintient deux branches. Un brouillon doit donc rester invisible tant qu’il n’est pas approuvé.
La relecture est un jugement
Une revue de code s’appuie sur des tests. La relecture d’une procédure, c’est un expert qui décide si une affirmation tient toujours. La forme de cette relecture influe sur l’envie de contribuer : une étude sur les bases de connaissances d’entreprise montre que des processus de validation transparents et tournés vers la progression des auteurs encouragent les contributions (Journal of Management Information Systems, 2009). KCS va plus loin et met en garde contre la règle du responsable unique : selon la méthode, la propriété individuelle des articles tue la gestion des connaissances, car plus personne n’ose modifier l’article d’un autre. Les deux positions se concilient : un responsable répond de l’exactitude, et chacun peut signaler ou corriger.
Ce que les sources ne tranchent pas
Aucune des sources de référence que nous avons lues ne répond à trois questions pourtant décisives.
À quelle fréquence relire ? Aucune ne justifie un intervalle par des données. Notre guide pour mettre à jour une base de connaissances compare ce que demandent KCS, le NHS, la Haute Autorité de santé et GOV.UK.
Qui est responsable quand les équipes changent, et que peut montrer une réponse d’IA ? Les sources demandent un responsable, mais disent peu de chose de la passation quand il part. Côté IA, l’ANSSI recommande de revoir les droits d’accès des outils d’IA générative aux espaces documentaires dès leur activation, puis régulièrement, par exemple tous les mois (avril 2024). Les agences de cybersécurité des États-Unis, du Royaume-Uni, d’Australie et de Nouvelle-Zélande ajoutent qu’une réponse d’IA doit être classifiée au même niveau que les données dont elle est issue (mai 2025). Aucune ne dit comment faire quand une réponse combine des documents aux droits différents. Dans MCP, l’autorisation est facultative, et la spécification précise que le protocole ne peut pas faire respecter ses principes de sécurité à lui seul. C’est à chaque implémentation d’appliquer les droits du lecteur.
Comment mesurer l’exactitude ? KCS est catégorique : fixer des objectifs sur l’activité corrompt la base de connaissances. Demandez dix articles par mois, vous obtiendrez dix articles par mois. La méthode recommande de suivre des résultats, mais ni elle ni aucune autre source lue ne définit une mesure de l’exactitude d’une base de connaissances.
Ces décisions vous reviennent : la plateforme doit vous laisser les appliquer, puis les ajuster.
Ce qu’une plateforme de connaissances doit offrir
Lue comme un cahier des charges, la transposition donne sept exigences pour toute plateforme qui sert collaborateurs et agents IA :
- Un responsable par article, et une passation organisée quand il quitte l’entreprise.
- Une approbation avant publication, pour les nouveaux articles comme pour les mises à jour.
- Toutes les versions conservées, avec les changements visibles et un retour possible.
- Des dates de revue qui créent une tâche pour le responsable, et la liste de ce qui est en retard.
- Un archivage qui retire l’article de la recherche sans le supprimer.
- Des modèles et des métadonnées lisibles par les personnes comme par les logiciels.
- Un accès unique pour les agents IA, qui applique les droits de chaque lecteur, et des modifications d’agents soumises à la même approbation que celles des personnes.
Comment nous l’appliquons chez Elium
Elium est une plateforme européenne de knowledge management, construite autour de cette liste. Chaque article a un responsable, et un administrateur peut transférer les articles d’une personne qui part à des successeurs, espace par espace. Un espace peut rendre l’approbation obligatoire pour les nouveaux articles et les mises à jour. Elium conserve toutes les versions d’un article, montre ce qui a changé et permet de restaurer une version antérieure. Une date de vérification place l’article dans les tâches de son responsable à l’échéance, et les articles archivés sortent de la recherche sans être supprimés.
Côté IA, Elium prend en charge MCP : des assistants comme ChatGPT ou Claude s’y connectent et lisent la même source que les équipes. L’accès passe par les droits de la personne connectée : un assistant ne voit que ce qu’elle a le droit de voir. Quand un assistant lit un article, il reçoit aussi son responsable, sa date de revue, son statut d’approbation et son éventuel archivage : il peut donc dire au lecteur si sa source est à jour. Quand il écrit, ses modifications sont enregistrées par défaut comme brouillons et suivent votre processus habituel de publication ou d’approbation.
L’intervalle de revue et la mesure de l’exactitude, c’est à vous de les fixer. Au Département de l’Orne, l’équipe informatique a fixé une date d’expiration et une revue annuelle pour chaque procédure : aucune ne reste active sans avoir été vérifiée.
Pour aller plus loin
- La garder exacte. Garder une base de connaissances exacte : responsables, revues, départs.
- Le volet IA. Le headless knowledge management sépare la source des écrans qui la lisent ; WYKIWYG montre qu’un assistant n’est jamais plus juste que ses documents.
- Comparer. Notre comparatif des outils de knowledge management.
- Utiliser un modèle. Planifiez vos revues avec le modèle de calendrier de revue des contenus.
- Le faire dans Elium. Découvrez Elium pour le support IT ou Elium pour les équipes IA & Data.
Le knowledge as code en bref
Le knowledge as code consiste à gérer les connaissances de l’entreprise comme du code : un responsable par article, une approbation avant publication, toutes les versions conservées et des contrôles automatiques sur ce qui n’est plus à jour. Il étend la documentation as code aux procédures, aux politiques internes et aux connaissances de support, pour que collaborateurs et agents IA lisent une seule source gouvernée.
La documentation as code consiste à écrire la documentation avec les outils du code : gestion de versions, texte balisé simple, revue de code et tests automatiques. Le knowledge as code garde les pratiques et laisse l’outillage de côté, car les auteurs sont des experts métier qui ne travaillent pas dans Git. Responsable, approbation, versions et contrôles passent dans la plateforme de connaissances.
Le plus souvent par une API ou par le Model Context Protocol (MCP). MCP ne fait pas respecter les droits à lui seul : la plateforme doit appliquer les droits d’accès de chaque lecteur et transmettre avec le contenu son statut, par exemple son responsable et sa date de revue.
Sources
- Write the Docs, Docs as Code, guide communautaire (non daté).
- Jen Lambourne, Government Digital Service, Why we use a "docs as code" approach for technical documentation, 25 août 2017.
- Home Office (Royaume-Uni), Engineering Guidance and Standards, Docs as code, mis à jour le 25 avril 2025.
- Lynda Cooper, ISO/IEC JTC 1/SC 40, ISO/IEC 20000-1 : implementing and auditing the knowledge requirement, avril 2025.
- Government Digital Service, GOV.UK content and publishing guidance : Manage existing GOV.UK content et Retire outdated content.
- NHS, Content policy, relue le 14 octobre 2022.
- Haute Autorité de santé, SAMU : améliorer la qualité et la sécurité des soins, guide méthodologique, validé le 1er octobre 2020.
- OASIS, DITA Version 1.3 : sujets concept, tâche et référence, approuvé le 17 décembre 2015.
- Semantic Versioning 2.0.0 et Keep a Changelog 1.1.0, conventions ouvertes.
- Consortium for Service Innovation, Knowledge-Centered Success Practices Guide (édition 2027, publiée en avril 2026) : techniques 2.1, 2.2, 5.3, 5.4 et 7.1.
- H. Zhang, S. Wang, T.-H. Chen, Y. Zou et A. E. Hassan, An empirical study of obsolete answers on Stack Overflow, IEEE Transactions on Software Engineering, 2019.
- A. Durcikova et P. H. Gray, How knowledge validation processes affect knowledge contribution, Journal of Management Information Systems 25(4), 2009.
- ANSSI, Recommandations de sécurité pour un système d’IA générative, version 1.0, 29 avril 2024.
- NSA, CISA, FBI, ASD’s ACSC, NCSC-NZ et NCSC-UK, AI data security : best practices for securing data used to train and operate AI systems, 22 mai 2025.
- Model Context Protocol, spécification, version 2026-07-28, section authorization et gouvernance.
