22 août 2026
Pourquoi Barkan lit l’écran, pas la doc
La documentation décrit le produit en général. Le DOM le décrit pour cet utilisateur, à cet instant. Plongée dans la façon dont Barkan transforme une page affichée en direct en données sur lesquelles un modèle peut agir.
Quand nous avons commencé à construire Barkan, l’architecture évidente était celle que tout le monde avait déjà livrée : vectoriser la documentation du produit, retrouver les passages pertinents pour une question, et laisser un modèle rédiger la réponse. C’est ce que nous avons construit en premier. Cela marchait assez bien pour une démo, et trop mal pour être livré ; le mode d’échec était toujours le même : la réponse était juste sur le produit et fausse sur l’utilisateur. Cet article raconte la décision qui a suivi — ancrer chaque réponse dans l’interface affichée en direct — et ce qu’elle exige concrètement.
L’échec qui a changé l’architecture
La question qui a fait tomber la version nourrie à la doc était banale. Un testeur a demandé « comment ajouter une deuxième licence ? » et a reçu une réponse nette, en six étapes, tirée tout droit du centre d’aide. L’étape quatre disait de cliquer sur Ajouter un membre. Sur l’écran du testeur, ce bouton était grisé, avec une infobulle expliquant que l’offre Launch est limitée à une licence.
La réponse n’était pas une hallucination. Elle était vraie, en général, et inutile dans ce cas précis. Le modèle ignorait que le bouton était désactivé, parce que rien dans la documentation ne pouvait lui dire à quoi ressemblait l’écran de ce compte à cet instant.
C’est la limite fondamentale de tout assistant dont le savoir vient de textes sur le produit : il connaît le produit tel qu’il a été conçu, pas tel qu’il s’affiche pour cet utilisateur. Et c’est précisément dans l’écart entre les deux que les utilisateurs restent bloqués.
Si une réponse dépend de quelque chose que l’utilisateur peut voir, le modèle doit pouvoir le voir aussi. La documentation a le droit d’expliquer pourquoi ; seule l’interface en direct a le droit de dire où.
Ce que « lire l’écran » veut dire
Il ne s’agit pas de captures d’écran, ni de déverser le HTML dans le prompt. Les deux sont tentants et les deux échouent : les captures d’écran perdent la structure dont un modèle a besoin pour agir, et le HTML brut d’une application moderne, ce sont des centaines de kilo-octets de bruit de framework où le signal utile est noyé.
À la place, quand un utilisateur pose une question, le widget capture un instantané enrichi du document affiché et l’envoie à l’API avec la question. Pour l’essentiel, il contient :
Couche · Ce qu’elle transporte · Pourquoi c’est important
Éléments interactifs · Boutons, liens, champs, chacun avec une référence stable et un libellé accessible · Pour que le modèle puisse pointer un élément précis et agir dessus
Relations · Quel libellé correspond à quel champ, quel bouton appartient à quel formulaire · Transforme « le champ e-mail » en élément concret
Faits d’interface · États désactivés, onglets sélectionnés, badges, compteurs, erreurs de validation · L’information « grisé sur Launch » que la doc n’a jamais eue
Blocs de contenu · Titres et textes visibles, dédoublonnés et tronqués · Assez de contexte pour comprendre la page, sans la page entière
Résumés de formulaires · Ce qui est rempli, ce qui est vide, ce qui est invalide · Permet au modèle de reprendre un workflow à moitié terminé
Surfaces actives et défilement · Fenêtres modales et panneaux ouverts, zone actuellement visible · Distingue « pas à l’écran » de « n’existe pas »
Métadonnées de la page · Route, titre, attributs data autorisés · Une orientation fiable et peu coûteuse
L’ensemble est conçu pour être léger, stable et honnête. Léger, pour tenir dans le budget de contexte en laissant de la place pour réfléchir. Stable, pour qu’un même élément garde la même référence d’un tour à l’autre : c’est ce qui rend possibles le pointage et les actions en plusieurs étapes. Honnête, pour que le modèle ne voie jamais un élément que l’utilisateur ne voit pas.
Les trois problèmes d’ingénierie que cela pose
Ancrer les réponses dans le DOM règle le problème du « faux sur l’utilisateur » et en crée aussitôt trois autres. Ils en valent tous la peine, mais ils sont bien réels.
1. L’interface bouge
Un index de documentation change quand quelqu’un modifie une doc. Le DOM change dès qu’il se passe quoi que ce soit : une liste déroulante s’ouvre, une notification s’affiche, une liste finit de se charger. Un instantané pris une seconde trop tôt décrit une page qui n’existe plus.
Nous gérons cela de deux façons. L’instantané est capturé une fois la page stabilisée : nous attendons que l’activité réseau en cours et la mise en page se calment, dans la limite d’un délai maximal, pour qu’une page agitée ne puisse pas bloquer la réponse indéfiniment. Et en mode action, chaque action est suivie d’une nouvelle capture silencieuse avant que l’étape suivante ne soit décidée : le modèle agit donc toujours sur la page telle qu’elle est, et non telle qu’elle était.
2. Des références stables sur un arbre instable
Dire au modèle « clique sur le troisième bouton » est fragile. Lui dire « clique sur l’élément d’id b17 » ne fonctionne que si b17 désigne la même chose au tour suivant. Les frameworks modernes refont le rendu de manière agressive : nous ne pouvons donc pas nous appuyer sur l’identité des nœuds du DOM.
Nos références sont dérivées de ce qu’un humain utiliserait pour reconnaître l’élément — son rôle, son libellé, sa position parmi ses voisins, la région qui l’englobe — et nous conservons une table éphémère qui associe chaque référence au nœud réel. Quand cette table devient obsolète, l’action échoue de manière explicite et le modèle relit la page plutôt que de cliquer au mauvais endroit. Mieux vaut une action ratée que l’on voit qu’une action réussie sur le mauvais élément.
3. Ce qu’il ne faut pas envoyer
L’instantané enrichi d’un vrai produit contient de vraies données : des noms de clients dans un tableau, le total d’une facture, un e-mail dans un champ de formulaire. Tout envoyer à un modèle par défaut n’est pas acceptable, et « on en a besoin pour le contexte » n’est pas une raison suffisante.
L’instantané est minimisé côté client, avant de quitter la page. Le texte visible est tronqué et dédoublonné, les valeurs des champs sont résumées en rempli / vide / invalide au lieu d’être copiées, et seule une liste autorisée d’attributs data est transmise. Le but : que le modèle sache qu’il existe un tableau de clients de 48 lignes surmonté d’un champ de recherche, pas qui sont ces clients.
La minimisation coûte parfois une réponse. Si l’utilisateur demande « pourquoi le total de cette facture est-il faux ? », le modèle ne peut pas voir le montant. Nous pensons que c’est le bon choix par défaut : il peut montrer le champ à l’utilisateur et expliquer comment le total est calculé, sans que le chiffre ne quitte jamais la page.
Montrer plutôt qu’expliquer
Une fois le modèle ancré dans la même interface que celle que regarde l’utilisateur, une chose devient possible, hors de portée de tout assistant nourri à la doc : il peut arrêter de décrire et commencer à pointer.
Quand la réponse fait référence à un élément, le widget y amène un curseur, sur la vraie page, puis attend. Au fil d’un workflow en plusieurs étapes, ce curseur conduit l’utilisateur de bouton en bouton — y compris d’une page à l’autre, puisque l’instantané est reconstruit sur la nouvelle route. La consigne et l’interface deviennent un seul et même objet, et l’étape de traduction qui rend la documentation si épuisante disparaît tout simplement.
N’importe quel assistant peut vous dire où se trouve le bouton. Toute la différence, c’est de pouvoir voir que vous êtes déjà sur la mauvaise page.
Là où la doc compte encore
Rien de tout cela ne veut dire que la documentation est inutile au modèle. Elle a simplement un autre rôle. La doc porte l’intention — à quoi sert une fonctionnalité, quand l’utiliser, ce que signifie un paramètre — et l’écran porte l’état. Une bonne réponse a souvent besoin des deux : la base de connaissances explique que les webhooks sont relancés trois fois, et l’écran montre que la dernière livraison de ce webhook a échoué.
Barkan puise donc bien dans la base de connaissances, mais il le fait après avoir lu l’écran, et l’écran l’emporte chaque fois que les deux divergent. Si la doc dit qu’il existe un bouton Ajouter un membre et que l’écran le montre désactivé, la réponse porte sur le bouton désactivé.
– Ancrez les réponses dans l’interface affichée, pas dans la doc. « Vrai en général » est la plus coûteuse des erreurs.
– Envoyez de la structure, pas des pixels ni du HTML brut : éléments interactifs, relations, faits d’interface, contenu résumé.
– Capturez une fois la page stabilisée, et recapturez après chaque action ; le DOM est une cible mouvante.
– Minimisez côté client. Le modèle doit connaître la forme des données, pas les données elles-mêmes.
– Pointez au lieu de décrire. Dès que vous voyez l’élément, vous pouvez le montrer.
L’installation tient toujours en une ligne
On pourrait craindre que « lire l’interface affichée » suppose une intégration profonde. Ce n’est pas le cas. Le widget tient dans une seule balise script, placée dans le layout que vous affichez déjà ; il monte sa propre racine dans un shadow DOM, observe la page depuis le navigateur, et n’a besoin ni d’annotations de routes ni de composants d’encapsulation.
<script async src="https://trybarkan.com/widget.js" data-barkan-site="site_your_key"></script>Tout ce qui est décrit plus haut se passe dans ce script. Le produit sur lequel il est installé n’a pas besoin de savoir que Barkan existe.
Installez la balise script, ouvrez votre application et posez-lui une question à laquelle votre doc ne sait pas répondre. 25 $ de crédits pour démarrer, sans carte bancaire.
« La plupart des utilisateurs ne veulent pas d’une réponse de plus. Ils veulent qu’on leur montre le chemin, ou que ce soit fait. Tout le produit est là. »
Gabriel Lancelot
Cofondateur de Barkan
