Quand l'IA devient aussi une cible de la documentation
Explorer comment dériver des représentations de connaissances orientées IA sans dupliquer la documentation.
Même connaissance. Différents consommateurs. Différents besoins de représentation.
La documentation technique a déjà connu une transformation majeure dans la manière dont elle est consommée.
Autrefois, la documentation désignait généralement une ressource relativement statique, souvent conçue pour être lue de manière séquentielle. Avec le Web, elle est devenue interrogeable, interconnectée et accessible à l'échelle de la page ou de la section. Les approches docs-as-code et la livraison continue sont allées plus loin, en intégrant la documentation dans un cycle de vie logiciel en constante évolution.
Une nouvelle transformation est aujourd'hui en cours :
les consommateurs de documentation ne sont plus exclusivement humains.
Les systèmes d'IA recherchent, interprètent, combinent et réutilisent la documentation.
- Parfois, ils servent d'interface entre la connaissance et un utilisateur humain, au travers d'un système RAG, d'un chatbot ou d'un agent documentaire.
- Dans d'autres situations, la connaissance peut être consommée par des machines avec peu, voire aucune représentation destinée à un humain.
Cela introduit de nouveaux modes de consommation et de nouvelles contraintes.
L'IA n'est pas seulement un outil pour la documentation. Elle devient aussi un consommateur de documentation.
La question n'est donc plus simplement de savoir comment donner accès à l'IA à la documentation existante, mais de déterminer si les représentations que nous avons conçues pour les humains sont également adaptées à une consommation prioritairement machine.
L'IA comme nouveau consommateur de documentation
██╗ ██╗███╗ ██╗ ██████╗ ██╗ ██╗██╗ ███████╗██████╗ ██████╗ ███████╗
██║ ██╔╝████╗ ██║██╔═══██╗██║ ██║██║ ██╔════╝██╔══██╗██╔════╝ ██╔════╝
█████╔╝ ██╔██╗ ██║██║ ██║██║ █╗ ██║██║ █████╗ ██║ ██║██║ ███╗█████╗
██╔═██╗ ██║╚██╗██║██║ ██║██║███╗██║██║ ██╔══╝ ██║ ██║██║ ██║██╔══╝
██║ ██╗██║ ╚████║╚██████╔╝╚███╔███╔╝███████╗███████╗██████╔╝╚██████╔╝███████╗
╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚══╝╚══╝ ╚══════╝╚══════╝╚═════╝ ╚═════╝ ╚══════╝
L'architecture documentaire a toujours été influencée par ses publics.
La documentation destinée aux humains combine l'information avec des éléments conçus pour faciliter la compréhension : navigation, explications progressives, hiérarchie visuelle, composants interactifs, illustrations et schémas.
Certains de ces éléments restent utiles aux systèmes d'IA. D'autres relèvent principalement de la présentation ou deviennent difficiles à interpréter lorsque des fragments individuels sont récupérés hors de leur interface d'origine.
À l'inverse, certaines informations qui n'ont pas nécessairement besoin d'être affichées explicitement à un lecteur humain peuvent être très utiles à une machine : provenance, auteur, date de dernière modification, statut dans le cycle de vie, compatibilité de version, relations entre concepts ou autres signaux de qualification.
L'accessibilité constitue un point de convergence intéressant. Des informations initialement conçues pour améliorer l'accessibilité humaine — par exemple un texte alternatif ou une structure sémantique — peuvent également rendre le contenu plus explicite pour les machines.
Cela ne signifie pas que l'IA a besoin d'une documentation simplifiée.
Supprimer des explications uniquement pour économiser des tokens peut aussi supprimer du contexte. Le sens et le contexte restent essentiels. Ce qui change, c'est la manière dont certaines informations peuvent devoir être exposées, structurées ou qualifiées.
La représentation doit donc dépendre de la tâche :
Un agent qui répond à des questions documentaires, un pipeline de retrieval qui construit un index, un agent de développement qui explore un repository et un processus autonome qui consomme des connaissances au travers d'une interface n'ont pas nécessairement besoin de la même représentation.
Lorsque l'IA devient un consommateur de documentation, la représentation devient une décision d'architecture.
Concevoir pour la consommation par l'IA
Avant de créer une représentation spécifique à l'IA, la première question à se poser est la suivante : de quoi le consommateur visé a-t-il réellement besoin ?
Dans certains cas, la documentation existante peut déjà apporter suffisamment de structure et de contexte. Dans d'autres, les informations pertinentes existent, mais restent implicites. Certaines informations peuvent également devoir être ajoutées spécifiquement pour une consommation par une machine.
Évaluer les informations disponibles
Concevoir une représentation orientée IA consiste donc à identifier :
ce qui existe déjà, ce qui doit être conservé, ce qui doit être rendu explicite et ce qui doit être ajouté.
| Informations disponibles | Pourquoi elles sont utiles à l'IA | Traitement possible |
|---|---|---|
| Contenu et explications | Apportent du sens et la connaissance du domaine | Conserver |
| Titres et descriptions | Identifient et résument les ressources | Conserver ou enrichir |
| Hiérarchie et navigation | Fournissent des relations contextuelles | Rendre explicites lorsque cela est utile |
| Auteur et dates de modification | Indiquent la provenance et la fraîcheur | Exposer sous forme de métadonnées |
| Versions et statut dans le cycle de vie | Aident à qualifier l'applicabilité | Exposer de manière cohérente |
| Relations entre concepts | Facilitent le retrieval et le raisonnement entre les ressources | Encoder explicitement |
| Taxonomies et terminologie contrôlée | Améliorent la cohérence et la découverte | Réutiliser et gouverner |
| Éléments d'interface interactifs | Peuvent masquer ou fragmenter l'information | Transformer lorsque nécessaire |
| Mise en page décorative et éléments visuels d'interface | Relèvent principalement de la présentation | Généralement omettre des représentations dérivées |
| Schémas et autres informations non textuelles | Peuvent contenir des connaissances techniques essentielles | Conserver sous une forme interprétable |
Le sens et le contexte ne doivent pas être remplacés par des métadonnées. Les métadonnées doivent aider les machines à qualifier et à relier la connaissance sous-jacente.
Privilégier les représentations textuelles lorsque c'est possible
Dans mes documentations techniques, je privilégie généralement les schémas Mermaid aux schémas PNG lorsqu'ils permettent de préserver le même sens.
La source reste textuelle, versionnable et transformable, tandis que les humains bénéficient toujours d'une représentation visuelle.
Cela ne garantit pas qu'un système d'IA interprétera correctement tous les schémas Mermaid. Mais cela permet aux consommateurs humains comme machine d'accéder aux informations sous-jacentes à la représentation visuelle.
Approches existantes pour une documentation orientée IA
L'idée de fournir aux machines une représentation différente de celle destinée aux humains n'est pas nouvelle.
Plusieurs approches commencent déjà à apparaître.
Markdown Twins
J'utilise ici le terme Markdown Twin pour désigner une représentation Markdown en texte brut d'un contenu également publié sous une autre forme, généralement en HTML.
Une page de documentation conçue pour des humains peut comporter une navigation, des composants de mise en page, des styles, des scripts et des éléments interactifs. Une représentation Markdown permet d'éliminer une grande partie de cette complexité visuelle et liée à l'interface tout en exposant le contenu dans une structure textuelle plus simple.
L'intérêt d'une telle représentation ne réside pas uniquement dans le format Markdown lui-même.
Elle peut apporter moins de bruit de présentation, davantage de structure explicite, de relations, de contexte et de métadonnées utiles aux machines.
Cette approche peut être pertinente pour un site documentaire dont le HTML publié est beaucoup plus complexe que son contenu sous-jacent.
Mais elle soulève immédiatement une question lorsque la source originale est déjà en Markdown, reStructuredText, AsciiDoc ou dans un autre format de texte structuré :
quelle valeur supplémentaire apporte le Twin ?
llms.txt
Jeremy Howard a introduit llms.txt en 2024 comme une proposition visant à aider les agents à découvrir et à parcourir les contenus d'un site adaptés aux LLM.
Le fichier sert principalement de point d'entrée orienté machine : il fournit du contexte et des liens vers des ressources pertinentes plutôt que de dupliquer un site entier.
La version 2, publiée en août 2026, formalise également la découverte de versions Markdown alternatives des pages. Son auteur indique une adoption par des milliers de sites et plusieurs plateformes documentaires.
Cependant, il s'agit toujours d'une proposition et non d'un standard Web universel.
Google Search a précisé en juin 2026 que llms.txt n'est pas nécessaire à Google Search et n'a aucun effet, positif ou négatif, sur la visibilité ou le classement dans les résultats de recherche. Il peut néanmoins rester utile à d'autres services et agents qui choisissent de l'exploiter.
Le signal important n'est donc pas qu'une convention se soit déjà imposée.
C'est plutôt que plusieurs conventions et implémentations apparaissent parce que la consommation par les machines devient un véritable cas d'usage documentaire.
Différents environnements documentaires, problèmes différents
La pertinence d'une représentation supplémentaire dépend également fortement de l'endroit où réside la documentation.
Toutes les documentations ne partent pas du même environnement
Au fil de mes projets de documentation technique, j'ai travaillé avec plusieurs modèles :
- une documentation clairement séparée du produit, comme des bases de connaissances Confluence ;
- une documentation docs-as-code maintenue dans des repositories Git ;
- une documentation étroitement liée au code ou générée à partir de celui-ci, comme les descriptions d'API et la documentation du code ;
- des ressources techniques hybrides, comme les notebooks Python, qui combinent contenu exécutable et explications.
Créer une représentation supplémentaire a des implications très différentes selon les cas.
Limite 1 — Déplacer la connaissance vers un autre format
Créer une représentation Markdown peut nécessiter d'extraire les connaissances de leur environnement de rédaction et de les convertir vers un autre format.
Pour une base de connaissances Confluence, cela implique à la fois de sortir de la plateforme d'origine et d'en traduire les structures.
Même entre des formats documentaires textuels, comme reStructuredText, AsciiDoc et Markdown, la transformation ajoute une étape supplémentaire.
L'IA peut contribuer à la conversion, mais celle-ci doit malgré tout préserver la structure, le sens et les relations.
Limite 2 — Créer un autre corpus
Un Twin peut devenir exactement ce que son nom suggère : un double.
Cela pose particulièrement problème lorsque la base de connaissances d'origine contient les incohérences, informations dupliquées, pages obsolètes ou problèmes de gouvernance qu'il a justement fallu résoudre pour rendre la connaissance fiable.
Making Heterogeneous Knowledge AI-Ready pour découvrir comment construire une base de connaissances fiable.
Créer un second corpus maintenu manuellement risque de reproduire les mêmes problèmes ailleurs.
Base de connaissances ------------------> Documentation destinée aux humains
|
└---- copie manuelle -----------> Twin IA
La connaissance évolue -----------------> mise à jour
Le Twin IA évolue indépendamment -------> dérive
L'objectif ne devrait pas être de recréer en texte brut la fragmentation que nous avions précédemment cherché à résoudre.
Limite 3 — Qui est responsable du Twin ?
Un second corpus crée également un problème de cycle de vie.
- Qui le génère ?
- Qui le valide ?
- Qui le met à jour lorsque sa source évolue ?
- Qui vérifie que les deux représentations restent alignées ?
Et si l'IA effectue ces tâches de maintenance, qui valide les résultats générés par l'IA ?
Il s'agit de questions de gouvernance documentaire, et pas simplement de conversion de format.
Dériver, ne pas dupliquer
Mon alternative consiste à considérer la représentation orientée machine comme un artefact dérivé, plutôt que comme un corpus documentaire indépendant à maintenir.
Le principe est simple : dériver, ne pas dupliquer.
Du principe au processus
Au lieu de maintenir manuellement une seconde version, un processus contrôlé peut sélectionner, combiner, réorganiser ou enrichir la connaissance issue de sources faisant autorité, selon des besoins de consommation définis au préalable.
Ces consommateurs peuvent être des humains ayant différents besoins d'information, des agents, des systèmes de retrieval et d'indexation, des assistants de développement ou d'autres processus machine.
La représentation obtenue peut être :
- générée lors du build de la documentation ;
- actualisée lorsque la connaissance faisant autorité évolue ;
- assemblée dynamiquement ;
- stockée et versionnée sous forme d'artefact ;
- ou exposée au travers d'une interface lorsqu'elle est nécessaire.
Cela n'élimine pas tous les risques.
Une transformation peut introduire des erreurs. Des résumés générés peuvent déformer le sens. Les métadonnées peuvent devenir incohérentes. Les pipelines automatisés doivent être validés.
Un modèle de responsabilité différent
La dérivation modifie également la répartition de l'autorité et des responsabilités.
La connaissance reste sous l'autorité de sa source. La représentation dérivée devient une sortie disposant d'entrées traçables, de règles de transformation et de son propre cycle de vie.
Cette logique existe déjà dans d'autres workflows de publication technique : pipelines de build docs-as-code, références d'API générées, génération de données structurées et autres artefacts dérivés.
Le même principe peut être étendu aux représentations orientées IA.
Construire une représentation orientée IA
Ma propre réflexion sur cette question n'est pas partie d'un format de connaissances destiné à l'IA.
Elle est née de travaux antérieurs sur les données structurées, le SEO et le GEO, puis de mon travail sur la documentation agentique, la connaissance AI-ready et le docs-as-data.
Cette approche s'appuie sur des travaux antérieurs documentés dans :
- Building AI-Ready Documentation, une réflexion sur le SEO, le GEO et les données structurées appliqués à la documentation.
- How I Took Control of My Metadata, le premier d'une série d'articles de Blog consacrés à mon travail sur les données structurées et le JSON-LD.
Des données structurées aux connaissances orientées IA
Sur CoffeeCup.tech, j'ai développé un plugin Docusaurus qui génère des données structurées pour chaque page.
Le mécanisme combine deux types d'informations :
- des informations partagées définies de manière centralisée ;
- des informations propres à chaque page, récupérées depuis le front matter.
Le plugin assemble ces éléments sous forme de JSON-LD et injecte les données structurées ainsi obtenues dans le <head> de la page, où elles sont destinées à un public machine spécifique : les moteurs de recherche et les systèmes d'indexation.
Le lecteur humain ne voit pas cette représentation.
Pourtant, elle décrit le même contenu.
Ce mécanisme m'a amenée assez naturellement à envisager une autre possibilité architecturale.
Je pense que le même principe peut être étendu au-delà des données structurées pour créer des représentations de connaissances orientées IA.
L'implémentation des données structurées distribue les informations à l'endroit où il est le plus pertinent de les maintenir, puis assemble automatiquement une représentation destinée aux machines.
Cette même logique pourrait être reprise à une échelle plus large pour la consommation par l'IA.
Réutiliser ce qui existe déjà. Ajouter uniquement ce dont la consommation par l'IA a besoin. Assembler automatiquement la représentation.
Réutiliser les connaissances et métadonnées existantes
La documentation contient déjà des informations qui peuvent être réutilisées.
-
Les titres, descriptions, taxonomies, versions, relations existantes, types de contenu, auteurs, dates, références de code et autres métadonnées peuvent contribuer à une représentation orientée machine.
-
Certaines informations concernent l'ensemble du système de connaissances.
-
D'autres sont propres à une ressource particulière.
L'architecture n'a pas besoin de dupliquer les informations partagées dans chaque document. Un pipeline de transformation peut assembler des informations globales et des informations propres à une source, comme le fait déjà mon plugin de données structurées pour le JSON-LD.
Qualifier et relier, sans remplacer
Le point essentiel est que les métadonnées doivent qualifier et relier la connaissance plutôt que la remplacer.
Par exemple, identifier une page comme une procédure d'installation est utile. Mais le consommateur doit toujours pouvoir accéder à la procédure d'installation elle-même, ainsi qu'à ses prérequis et conditions d'application.
Prendre en compte l'environnement de rédaction
Les possibilités dépendent également de l'environnement de rédaction.
-
Les environnements docs-as-code basés sur Markdown permettent de maintenir particulièrement facilement des métadonnées personnalisées dans le front matter.
-
Les plateformes de gestion des connaissances comme Confluence, Notion ou SharePoint proposent généralement un modèle de métadonnées différent et parfois plus contraint ; les informations supplémentaires peuvent donc devoir être stockées ou dérivées autrement.
Ajouter des connaissances et métadonnées spécifiques à l'IA
Lorsque les informations existantes ne suffisent pas, plusieurs stratégies peuvent être envisagées.
Enrichir le front matter
Le front matter Markdown peut contenir des champs structurés supplémentaires dès lors que le système chargé de les traiter sait comment les interpréter.
Une architecture documentaire peut donc introduire des champs décrivant des relations ou la sémantique du contenu, par exemple :
documentationType: installation
isPartOf: getting-started
relatedTo:
- prerequisites
- configuration
La possibilité technique d'ajouter des champs YAML arbitraires n'est pas la principale difficulté.
La question architecturale consiste à déterminer si leur signification est définie de manière suffisamment cohérente pour que producteurs et consommateurs puissent les comprendre.
Les vocabulaires existants peuvent aider. Schema.org, par exemple, fournit déjà des relations telles que ``isPartOf, hasPart, isBasedOnetabout`.
Des données structurées aux relations entre connaissances
Cette question m'était déjà familière grâce à mon travail sur les données structurées. En parcourant le vocabulaire Schema.org pour CoffeeCup.tech, j'ai étudié comment les relations, les types et les métadonnées pouvaient décrire un contenu documentaire au-delà de ce qui est directement visible sur la page.
J'avais déjà commencé à explorer cette question en janvier 2026 dans mon article de Blog "Structured Data and Documentation Sites". Ce travail est ensuite devenu l'un des fondements de ma réflexion sur la documentation orientée IA.
Mais une représentation IA spécifique à la documentation peut également nécessiter des concepts qui ne sont pas couverts par un vocabulaire Web générique.
C'était l'une des questions que je me posais avant d'explorer l'Open Knowledge Format (voir plus bas) : jusqu'où peut-on ou doit-on encoder la sémantique des connaissances dans le front matter, et qui définit le vocabulaire?
Intégrer des connaissances structurées supplémentaires dans le contenu
Dans les environnements où les métadonnées personnalisées sont difficiles à gérer, des informations utiles orientées machine peuvent également être intégrées directement dans la documentation.
Cela peut prendre la forme :
- d'un résumé structuré ;
- de titres de sections standardisés ;
- d'un bloc de connaissances visible ;
- ou d'un fragment spécifiquement conçu pour être consommé à la fois par des humains et des machines.
Cette approche peut être particulièrement pertinente pour des bases de connaissances comme Confluence, Notion ou SharePoint, où une personnalisation de type front matter est moins naturelle.
Stocker ailleurs des ressources de connaissances dédiées
Certaines ressources spécifiques à l'IA peuvent également être maintenues séparément lorsqu'elles ne trouvent pas naturellement leur place dans une page documentaire donnée.
Elles peuvent inclure des définitions partagées, des relations entre documents, des résumés contextuels ou d'autres connaissances structurées.
Un serveur MCP peut alors exposer ces ressources à un agent.
Dans cette architecture, MCP constitue un mécanisme de consommation et d'exposition, et non la représentation de la connaissance elle-même.
Séparer la connaissance de sa représentation
La dérivation commence par identifier ce qui est réellement dérivé : non pas la page elle-même, mais la connaissance qu'elle porte et qualifie.
Cela s'inscrit naturellement dans une approche docs-as-data.
La documentation peut alors être envisagée selon plusieurs couches.
- Couche de connaissance – Faits, explications, données, code, métadonnées, contexte et relations.
- Couche de présentation – Identité graphique, mise en page, hiérarchie visuelle, interactions et dispositifs d'accessibilité.
- Couche de représentation – Markdown, HTML, JSON, YAML, graphes, hiérarchie et structures de navigation.
- Couche de consommation – Manière dont les humains ou les machines parcourent, combinent et utilisent ces représentations.
Ces couches se recoupent.
L'accessibilité en est un bon exemple : les textes alternatifs ou le HTML sémantique servent avant tout à rendre le contenu accessible aux personnes, mais cette sémantique supplémentaire peut également bénéficier aux machines.
On peut également établir un parallèle, à grands traits, avec les API : la ressource sous-jacente ne change pas nécessairement parce que différentes représentations ou interfaces l'exposent à différents consommateurs.
Séparer ces couches ne signifie pas qu'elles doivent toutes être physiquement séparées.
Cela permet simplement de rendre explicites leurs différentes responsabilités.
Des sources de connaissances aux représentations IA
Une fois la connaissance, la représentation et la consommation envisagées séparément, plusieurs architectures de pipeline deviennent possibles.
L'objectif n'est pas nécessairement de créer une seule source physique de connaissances.
Il s'agit plutôt d'établir un socle de connaissances gouverné à partir duquel des représentations adaptées peuvent être produites.
Trois modèles simplifiés permettent d'illustrer les possibilités.
Dérivation à partir d'une source unique
Une source vers une représentation
Un seul environnement documentaire reste la source faisant autorité.
Documentation faisant autorité ──> Spécification de transformation ──> Représentation orientée IA
Par exemple, un site documentaire ou une base de connaissances Confluence peut être transformé en une représentation enrichie de métadonnées supplémentaires, de relations explicites ou de résumés structurés.
Le point essentiel est que la représentation dérivée est générée selon des règles définies pour les entrées, les traitements et les sorties.
C'est l'architecture la plus proche du concept de Twin initial, mais sans maintenir le Twin de manière indépendante.
Agrégation de connaissances
Plusieurs sources vers une représentation
La connaissance peut déjà être distribuée entre plusieurs sources faisant autorité.
Confluence ────────────────┐
Repository Git ────────────┼──> Agrégation / qualification ──> Représentation IA
Métadonnées partagées ─────┤
Autres ressources ─────────┘
L'objectif n'est pas de tout copier dans un nouvel environnement de rédaction.
Le pipeline combine les informations pertinentes provenant de plusieurs emplacements afin de fournir une couche de consommation cohérente.
Cette approche peut être particulièrement adaptée aux écosystèmes documentaires hétérogènes, dans lesquels les connaissances techniques sont réparties entre documentation produit, repositories de code et bases de connaissances.
Publication de plusieurs représentations
Un socle vers plusieurs représentations
Une architecture plus ambitieuse et prospective place la connaissance structurée plus tôt dans le cycle de vie.
Socle de connaissances gouverné ---+--> Documentation destinée aux humains
+--> Représentation orientée IA
+--> Recherche / autre représentation
Les sorties destinées aux humains et aux machines deviennent alors des représentations alternatives produites à partir du même socle gouverné.
Ce modèle peut être particulièrement intéressant lorsqu'on conçoit une nouvelle architecture docs-as-code ou docs-as-data, plutôt que lorsqu'on cherche à adapter un patrimoine documentaire existant.
Il soulève également des questions plus complexes concernant les workflows de rédaction, la responsabilité des sources, la validation et le niveau de structuration que doit atteindre ce socle commun.
Mes schémas ci-dessus sont volontairement simplifiés.
Les trois architectures peuvent coexister, et les organisations peuvent progressivement passer de la dérivation d'une documentation existante à une architecture de connaissances commune plus structurée.
Gouvernance et cycle de vie
Ajouter des informations orientées machine crée de nouvelles responsabilités en matière de gouvernance documentaire.
Cela devient particulièrement important lorsque les contenus sont produits par plusieurs auteurs.
Si les auteurs créent indépendamment des valeurs pour documentationType, les relations, les statuts ou les résumés, la couche orientée machine peut développer les mêmes incohérences que la documentation destinée aux humains.
Les métadonnées nécessitent donc elles aussi une gouvernance.
Les mécanismes de contrôle peuvent notamment inclure :
- des vocabulaires contrôlés ;
- des conventions de nommage ;
- des schémas ;
- des règles de validation ;
- la définition des responsabilités ;
- des règles de source of truth ;
- des processus de synchronisation ;
- des statuts de cycle de vie ;
- du monitoring ;
- des règles de retrait.
L'automatisation peut réduire le travail répétitif, mais elle ne doit pas supprimer la responsabilité.
Le rôle du rédacteur technique
Cette architecture renforce également le rôle d'un rédacteur technique expert*.
Le travail ne se limite pas à produire du texte.
Un rédacteur technique peut :
- identifier et qualifier les connaissances faisant autorité ;
- restructurer le contenu ;
- concevoir et gouverner les métadonnées ;
- définir les relations et les informations contextuelles ;
- créer des résumés orientés IA ;
- concevoir les surfaces de connaissances des agents ;
- spécifier les entrées et les sorties attendues ;
- valider les représentations générées ;
- contribuer aux pipelines de transformation ;
- et maintenir la cohérence tout au long du cycle de vie documentaire.
L'implémentation technique peut nécessiter une collaboration avec des équipes Engineering, Data ou IA.
Mais l'architecture documentaire, le modèle d'information et les règles de qualité restent des sujets documentaires.
*Une rédactrice technique experte, en l'occurence
Une architecture qui reste à tester
Les approches présentées ici sont pour l'instant des hypothèses architecturales plutôt que les résultats d'une implémentation achevée.
Ma prochaine étape consistera à les expérimenter en pratique, soit dans le cadre de futurs projets documentaires, soit en développant ma propre base de connaissances personnelle orientée IA.
L'objectif sera de tester les cas dans lesquels la dérivation fonctionne, quelles informations sont réellement utiles, quel niveau de métadonnées est nécessaire et dans quelles situations l'automatisation apporte de la valeur plutôt qu'une complexité supplémentaire.
Approches émergentes et questions ouvertes
Ma réflexion sur les représentations orientées IA s'est développée progressivement à travers plusieurs domaines de mon travail :
données structurées → documentation agentique → connaissance AI-ready → représentation orientée IA
Ce n'est qu'ensuite que j'ai exploré des initiatives émergentes qui répondent à certaines de ces mêmes questions.
Cette chronologie est importante.
Le principe architectural décrit plus haut ne découle pas d'OKF. En revanche, OKF fournit désormais un cadre externe intéressant auquel confronter ces idées.
Open Knowledge Format (OKF)
Google a présenté l'Open Knowledge Format en juin 2026 comme une spécification ouverte formalisant ce qu'il appelle le modèle LLM-wiki.
Google décrit OKF comme un :
"standard adapté aux agents et aux humains pour représenter les métadonnées, le contexte et les connaissances sélectionnées dont les systèmes d'IA modernes ont besoin."
OKF représente les connaissances au moyen de documents Markdown et de front matter YAML. Dans sa version actuelle v0.2, la provenance, la confiance, la fraîcheur et le cycle de vie constituent des préoccupations de premier ordre, tout en conservant volontairement une grande extensibilité.
C'est particulièrement intéressant au regard des questions soulevées précédemment dans cette page.
OKF impose un champ type, mais autorise les métadonnées définies par les producteurs et demande aux consommateurs de tolérer les champs supplémentaires qu'ils ne connaissent pas. Il apporte ainsi une réponse possible à la question de savoir comment ajouter une sémantique spécifique à la documentation sans imposer un schéma universel pour chaque concept.
Il distingue également explicitement les producteurs — humains, agents ou pipelines d'export — des consommateurs, tels que les agents, interfaces utilisateur, index de recherche ou code déterministe.
Cette séparation correspond étroitement à l'architecture producteurs / représentation / consommateurs explorée ici.
OpenWiki
OpenWiki apporte une perspective d'implémentation plus concrète.
LangChain le décrit comme un outil open source en ligne de commande qui crée et maintient des wikis Markdown consacrés à des bases de code ou à des connaissances personnelles.
Sa documentation précise :
"Les humains peuvent parcourir le même Markdown [...] mais le public principal est constitué des agents."
Cette phrase résume une idée importante : une documentation orientée machine n'a pas nécessairement besoin d'être illisible pour les humains. Elle peut rester lisible par des humains tout en étant architecturée en priorité pour une consommation par des machines.
OpenWiki peut produire des bundles compatibles avec OKF v0.2, conserver les champs d'extension définis par les producteurs et maintenir des informations de provenance et de vérification. Il utilise également des liens Markdown pour exprimer les relations entre concepts.
Son traitement des schémas est tout aussi intéressant : OpenWiki génère des diagrammes Mermaid lorsqu'ils facilitent la compréhension des informations et en valide la syntaxe. Cela rejoint la préférence pour les représentations textuelles évoquée précédemment.
Le projet comprend également un visualiseur qui expose le même wiki Markdown sous forme de graphe interactif de nœuds et de lecteur documentaire — un exemple intéressant d'un même corpus de connaissances permettant une autre forme d'exploration.
Des approches très récentes
Ces initiatives sont encore très récentes.
Nous ne disposons pas encore de suffisamment de recul pour évaluer leur coût de maintenance, leur interopérabilité, leurs modes d'adoption ou leur pertinence dans différents environnements documentaires.
La spécification OKF actuelle souligne elle-même que la représentation des connaissances pour les agents IA évolue rapidement et que des conventions incompatibles apparaissent.
Cela rend l'expérimentation particulièrement importante.
Parmi les questions que je souhaite explorer :
- Avec quelle fiabilité peut-on transformer une documentation hétérogène tout en préservant son sens et sa provenance ?
- Quelles métadonnées existantes améliorent réellement la consommation par l'IA ?
- Jusqu'où les métadonnées spécifiques à l'IA restent-elles utiles avant de devenir une nouvelle charge de maintenance ?
- Comment représenter les relations entre les ressources documentaires ?
- Comment garantir la cohérence des métadonnées et des résumés dans des environnements multi-auteurs ?
- Dans quels cas l'enrichissement de la documentation existante suffit-il ?
- Quand un bundle de connaissances généré séparément apporte-t-il une réelle valeur ?
- Comment valider et synchroniser les représentations générées ?
- Des standards comme OKF peuvent-ils offrir une interopérabilité réellement exploitable entre systèmes documentaires et consommateurs IA ?
Ces approches feront partie de mes prochaines expérimentations, dont les retours d'implémentation seront publiés dans le Blog.
L'évolution sera probablement progressive plutôt qu'une refonte complète des systèmes documentaires existants : enrichir progressivement les sources de connaissances existantes tout en introduisant des représentations orientées machine lorsqu'elles apportent une valeur mesurable.
Conclusion — La documentation a un nouveau consommateur
Depuis plusieurs années, mon travail documentaire m'amène à prêter attention à deux dimensions complémentaires des contenus publiés :
ce que les humains voient et utilisent, et ce que les machines peuvent lire derrière ou à côté.
-
Le front matter fournit depuis longtemps des informations clés à la fois pour le fonctionnement interne des sites documentaires et pour leur indexation par les moteurs de recherche.
-
Les données structurées ont rendu explicite pour les moteurs de recherche cette distinction entre humains et machines.
-
Le docs-as-data a prolongé cette logique en considérant la structure et les métadonnées comme des composantes porteuses de sens de la documentation.
-
L'IA agentique a montré comment des systèmes d'IA consomment activement la documentation.
-
La connaissance AI-ready a mis en évidence la nécessité de disposer de contenus fiables, de signaux de qualification et d'une gouvernance.
La question suivante en découle naturellement :
qu'est-ce qui change lorsque l'IA elle-même devient un consommateur de documentation ?
Ma réponse actuelle n'est pas de créer par défaut un second corpus documentaire.
Il s'agit plutôt de partir de connaissances gouvernées, de comprendre le consommateur visé, de réutiliser les informations existantes, d'ajouter uniquement ce qui est nécessaire et de dériver des représentations adaptées au moyen de processus contrôlés.
Des initiatives émergentes comme OKF et OpenWiki montrent que des questions similaires commencent aujourd'hui à être explorées plus largement.
Les architectures et les standards sont encore en train d'évoluer.
Mais le changement de public, lui, est déjà là.
Concevoir la documentation pour les humains. Architecturer la connaissance pour tous ses consommateurs.
© Autrice : Florence Venisse, experte en documentation technique & IA – Première version datée du 09 octobre 2026 :::