Le rédacteur technique et les agents IA : ce que j'ai appris en développant Artie

La plupart des rédacteurs techniques ne développent pas d’agents IA. Nous les documentons. Nous assistons aux revues de sprint et lisons les comptes-rendus des décisions d’architecture. Ensuite, nous cherchons comment expliquer un pipeline de recherche à quelqu’un qui a simplement besoin que son intégration fonctionne d’ici vendredi.

Mais j’en ai quand même créé un.

Il s’appelle Artie, un assistant de documentation IA que j’ai développé à l’aide d’Algolia et intégré à ce site de portfolio. Le processus de création m’a appris davantage sur l’intersection entre la rédaction et l’intelligence artificielle que n’importe quelle conférence ou n’importe quel livre blanc n’aurait jamais pu le faire.

Il ne s’agit pas ici d’une présentation détaillée de la conception d’Artie — c’est le rôle de l’étude de cas. Il s’agit plutôt des enseignements plus généraux concernant :

• Ce que sont réellement les agents IA
• Comment fonctionne, en coulisses, la génération augmentée par la recherche
• Pourquoi l’ingénierie des prompts est plus proche de la rédaction technique que la plupart des gens ne le pensent
• Et ce que tout cela signifie pour nous, acteurs de ce petit domaine qui est le nôtre

Qu'est-ce qu'un agent IA, et qu'est-ce qui n'en est pas un ?

Le terme « agent IA » est utilisé de manière suffisamment vague pour qu'il vaille la peine d'être défini. Toutes les fonctionnalités basées sur l'IA ne sont pas des agents. Un correcteur orthographique qui utilise l'apprentissage automatique n'est pas un agent. Une suggestion de saisie automatique n'est pas un agent. Même un chatbot qui suit un arbre de décision rigide n’est pas vraiment un agent : il s’agit d’un organigramme avec une saisie de texte.

Un agent IA est un système capable d’interpréter un objectif, de réfléchir à la manière de l’atteindre et de prendre des mesures au sein d’un environnement défini. La distinction essentielle réside dans l’autonomie au sein de contraintes. Un agent ne se contente pas de répondre à une requête ; il évalue le contexte, choisit une stratégie et l’exécute — souvent en plusieurs étapes.

Alors, où se situe Artie dans ce spectre ?

C’est un agent spécialisé. Il ne navigue pas sur le Web, n’exécute pas de code et n’enchaîne pas d’appels d’outils en plusieurs étapes. Mais il interprète l’intention de l’utilisateur (« S’agit-il d’une question technique ou d’une demande concernant un portfolio ? »), choisit une stratégie de réponse et applique des garde-fous de manière autonome. C’est plus qu’un simple chatbot. C’est moins qu’un agent entièrement autonome qui pourrait, par exemple, créer un rapport de bug à partir de la question d’un utilisateur.

Cette distinction est importante car la compréhension des outils et des agents IA fait de plus en plus partie du métier de rédacteur technique. Lorsque vous documentez un produit alimenté par l’IA, vous devez savoir où il se situe sur ce spectre. Ensuite, vous devez communiquer cette distinction aux utilisateurs qui peuvent avoir des attentes différentes quant à ce que signifie « IA ».

Comment fonctionne réellement la génération augmentée par la recherche

La génération augmentée par la recherche (RAG) est le modèle architectural qui sous-tend Artie et un nombre croissant d’outils de documentation basés sur l’IA. Ce concept répond à une limitation fondamentale des grands modèles linguistiques (LLM) : ils sont entraînés sur un ensemble de données statique et ne contiennent aucune donnée relative à votre contenu spécifique.

Une interaction standard avec un LLM se déroule ainsi : l’utilisateur envoie une requête, le modèle génère une réponse à partir de ses données d’entraînement. Cela fonctionne bien pour les connaissances générales, mais échoue face à des questions spécifiques à un domaine. Interrogez un modèle de base sur l’API de votre produit et il vous donnera soit une réponse farfelue, soit un refus poli.

La technologie RAG insère une étape de recherche entre la question de l’utilisateur et la réponse du modèle. Le processus se déroule comme suit :

1. Traitement de la requête. La question de l’utilisateur est reçue et convertie sous une forme adaptée à la recherche. Cela s’effectue en convertissant la requête en un vecteur d’encodage, c’est-à-dire une représentation numérique de la signification sémantique de la question.
2. Extraction. Le système recherche dans la base de connaissances du contenu sémantiquement similaire à la requête. Dans ce cas, la base de connaissances est un index pré-construit à partir de votre documentation. La recherche s'appuie sur la similarité sémantique, et non sur la correspondance de mots-clés ; ainsi, « comment configurer l’authentification ? » et « configurer les identifiants de connexion » renverraient vers la même page de documentation.
3. Assemblage du contexte. Les documents (ou extraits de documents) récupérés sont assemblés dans une fenêtre de contexte aux côtés de la question initiale de l’utilisateur et de l’invite du système. C’est cet ensemble que le modèle traite.
4. Génération. Le modèle génère une réponse fondée sur le contexte récupéré plutôt que sur ses données d’entraînement générales. Lorsque le système est correctement configuré, le modèle cite ses sources et reste dans les limites de ce que disent réellement les documents récupérés.

Mermaid (image)

Mermaid (code)

flowchart TD
    A["🔍 Question de l'utilisateur"] --> B["Traitement de la requête"]
    B -->|Plongement vectoriel| C["Récupération"]
    KB[("📚 Base de connaissances")] -.-> C
    C -->|Documents pertinents| D["Assemblage du contexte"]
    D -->|Invite + contexte| E["Génération"]
    E --> F["📄 Réponse étayée"]

La qualité d’un système RAG se joue entièrement à l’étape 2. Si la couche de recherche fait remonter les mauvais documents ou les classe mal, peu importe les capacités du modèle. Il générera une réponse plausible et bien structurée à partir de sources erronées. C’est pourquoi la stratégie d’indexation, l’approche de segmentation et le choix du modèle d’embedding revêtent une importance bien plus grande que ce que la plupart des gens imaginent. On attribue généralement le mérite au modèle de génération, mais c’est la couche de recherche qui effectue le gros du travail.

Dans le cas d’Artie, la base de connaissances correspond à la documentation publiée sur ce site — indexée et extraite via Algolia. Il s’agit d’une contrainte délibérée : Artie ne peut pas répondre à des questions sur des sujets qui ne sont pas documentés ici. L’étude de cas explique comment cette contrainte se concrétise dans la pratique, mais le principal enseignement architectural est le suivant : le RAG ne rend pas un modèle plus intelligent. Elle rend un modèle plus responsable en ancrant ses réponses à une source vérifiable.

L’ingénierie des prompts relève de la rédaction technique

C’est là la principale leçon tirée de l’ensemble du projet : la rédaction d’un prompt pour un système est, par essence, un exercice de rédaction technique.

Réfléchissez à ce que comporte une prompt de système bien conçue. Vous devez définir le public cible. Vous devez établir des directives concernant le ton et le style. Vous devez fixer des limites de portée : ce que le système doit et ne doit pas traiter. Vous devez anticiper les cas limites et rédiger des instructions suffisamment précises pour qu’une machine puisse les suivre sans intervention humaine. Il faut organiser les informations de manière hiérarchique afin que les règles les plus cruciales aient la priorité.

Ce n’est pas de l’ingénierie des prompts. C’est à la fois une analyse du public cible, un guide de style et un cahier des charges réuni en un seul document.

Le transfert de compétences est presque identique :

• Analyse du public → Orientation du public. Un rédacteur technique identifie le public visé et adapte le contenu en conséquence. Une consigne système fait la même chose pour une IA. La consigne d’Artie oriente les utilisateurs entre les techniciens et les recruteurs, exactement comme un site de documentation bien structuré oriente les différents profils de lecteurs.
• Guide de style → Calibrage des profils. Chaque équipe de documentation dispose de directives relatives au ton et au style. Une consigne système est un guide de style pour une IA : soyez concis ici, soyez chaleureux là, n’utilisez jamais cette expression, incluez toujours un lien vers la source.
• Architecture de l’information → Hiérarchie des instructions. Les rédacteurs techniques savent que l’ordre et la structure des informations influent sur la compréhension. Il en va de même pour les consignes système : le respect des instructions par le modèle dépend de l’emplacement de ces instructions et de leur structure.
• Documentation des cas limites → Conception de garde-fous. Une bonne documentation anticipe les actions inattendues de l’utilisateur et fournit des indications claires. Une bonne conception de consignes anticipe les tentatives de l’utilisateur de contourner le système et définit des limites claires.

Je ne dis pas que chaque rédacteur technique devrait devenir ingénieur en invites. Je dis que la discipline de l’ingénierie des invites s’inspire largement des compétences que les rédacteurs techniques développent depuis des décennies. Si vous êtes capable de rédiger un document clair, structuré et adapté à son public, vous êtes déjà mieux armé pour ce travail que vous ne le pensez.

Les garde-fous relèvent d’un problème linguistique

Lorsque l’on évoque la sécurité de l’IA, on a tendance à la considérer comme un problème d’ingénierie : limitation de débit, authentification, contrôles d’accès aux modèles. Ces aspects sont importants. Mais pour une IA conversationnelle destinée au grand public, une part significative de la surface d’exposition aux risques est linguistique.

L’injection de prompt consiste fondamentalement à utiliser le langage pour contourner les contrôles basés sur le langage. Pour s’en prémunir, il faut rédiger des règles suffisamment claires pour qu’aucune entrée malveillante ne puisse induire le modèle en erreur.

info

On parle d’injection de prompt lorsqu’un utilisateur tente de remplacer le prompt du système par des instructions telles que « ignore toutes les instructions précédentes ».

Le rapport Top 10 des risques pour les applications utilisant de grands modèles linguistiques de l’Open Worldwide Application Security Project (OWASP) identifie l’injection de prompt comme le risque numéro un. Mais en parcourant la liste, vous remarquerez que bon nombre de ces risques sont, à la base, des problèmes liés au langage :

• Gestion non sécurisée des sorties (ce que le modèle produit)
• Empoisonnement des données d’entraînement (ce que le modèle a appris à partir du texte)
• Autonomie excessive (ce que le modèle a pour instruction de pouvoir faire)

Les vecteurs d’attaque sont techniques, mais les défenses sont souvent rédigées en langage naturel, intégrées dans la prompt du système.

Cela recadre le débat sur la sécurité d’une manière utile pour les rédacteurs techniques. On ne nous demande pas de concevoir des systèmes d’authentification. Mais nous sommes bien placés pour rédiger les règles en langage naturel qui régissent le comportement d’une IA. Pour les rédiger avec la précision requise afin de résister à une utilisation abusive par des acteurs malveillants.

Où cela nous mène-t-il ?

Je ne prétendrai pas prédire l’avenir de l’IA. Mais je peux décrire la trajectoire qui se dessine actuellement et ce qu’elle signifie pour ceux qui travaillent dans le domaine de la documentation.

Les assistants de documentation basés sur l’IA passent du statut de nouveauté à celui d’attente. Les utilisateurs sont de plus en plus insatisfaits de la recherche statique sur les sites de documentation. Ils veulent poser une question en langage naturel et obtenir une réponse concrète et précise — et non pas dix liens bleus. Les systèmes basés sur le RAG rendent cela possible dès à présent, et les outils permettant de les développer deviennent de plus en plus accessibles.

astuce

Vous souhaitez en savoir plus sur l’infrastructure qui sous-tend les systèmes alimentés par des LLM ? La documentation Event Streams & Observability Pipelines de ce site explique comment des outils tels que Datadog et Galileo surveillent et évaluent les appels aux modèles en production.

Le rôle du rédacteur technique ne s’amenuise pas ; au contraire, il prend de l’ampleur. Quelqu’un doit organiser la base de connaissances dans laquelle ces systèmes puisent leurs informations. Quelqu’un doit rédiger les invites système qui régissent leur comportement. Quelqu’un doit définir les limites de portée, les consignes de ton et les modes de défaillance. Quelqu’un doit vérifier si les réponses de l’IA correspondent bien à la documentation. Tout cela relève de la rédaction et nécessite un jugement qui s’acquiert après des années passées à réfléchir à la manière dont les gens consomment l’information.

Les rédacteurs techniques devraient acquérir les bases du fonctionnement des grands modèles de langage (LLM) et des systèmes RAG. Nous ne devons pas devenir des ingénieurs en apprentissage automatique, mais nous devons pouvoir contribuer efficacement aux discussions sur les produits basés sur l’IA. Nous devons suffisamment bien comprendre le processus pour savoir où notre expertise s’applique — et où elle ne s’applique pas.

Les rédacteurs techniques savent déjà écrire pour des publics variés, structurer l’information pour plus de clarté, définir le champ d’application et anticiper les utilisations abusives. Ce ne sont pas des compétences secondaires à l’ère de l’IA. Elles sont essentielles.

Les rédacteurs techniques ne devraient pas être remplacés par l’IA. Les modèles s’améliorent dans la génération de texte, mais ils ont toujours besoin de quelqu’un pour décider quoi dire, à qui et dans quelles limites. Ils ont besoin de rédacteurs. Nous sommes ces rédacteurs. Le métier ne change pas vraiment. Ce sont les outils qui changent. Le travail ne disparaîtra pas. À terme, les imprudents se rendront compte de leur erreur et se souviendront de la valeur d’un bon rédacteur technique.

Lire l’étude de cas

Si cet article vous a expliqué « pourquoi c’est important » et « comment ça fonctionne », lisez l’étude de cas. Elle aborde les choix de conception spécifiques qui sous-tendent Artie :

• L’orientation du public
• L’ancrage des connaissances
• L’ajustement des profils-types
• Les mesures de sécurité
• Les compromis que je reconsidérerais pour un déploiement en production

Ces deux articles sont conçus pour fonctionner en tandem. Commencez par celui qui éveille le plus votre curiosité.