Ce que la création d’un assistant de documentation IA m’a appris sur la rédaction technique

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

J’en ai quand même créé un.

Il s’appelle Artie, un assistant de documentation IA que j’ai développé avec Algolia. Il tourne dans ce site de documentation. Le créer m’a appris davantage sur la rédaction et l’IA que n’importe quelle conférence.

Il ne s’agit pas ici d’une présentation détaillée de la conception d’Artie. L’étude de cas s’en charge. Cet article porte sur les enseignements plus généraux :

• Ce que sont réellement les agents IA
• Comment fonctionne la génération augmentée par la recherche en pratique
• Pourquoi l’ingénierie des prompts est plus proche de la rédaction technique que la plupart des gens ne le pensent
• 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

Les gens appliquent le terme « agent IA » à tout, du correcteur orthographique à la saisie automatique. Les différences comptent. Toute fonctionnalité IA n’est pas un agent. Un correcteur orthographique qui utilise l’apprentissage automatique n’en est pas un. Une suggestion de saisie automatique non plus. Un chatbot qui suit un arbre de décision figé n’est qu’un organigramme avec une zone de texte.

Un agent IA est un système capable d’interpréter un objectif et d’agir en conséquence dans un environnement défini. L’autonomie dans certaines limites distingue un agent d’une boucle requête-réponse. L’agent lit le contexte et choisit une stratégie, parfois en plusieurs étapes.

Où se situe Artie sur ce spectre ?

Ce n’est pas un agent selon cette définition. 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. Algolia récupère les pages avant l’exécution du modèle. Le modèle les reçoit comme contexte. En revanche, il interprète l’intention et applique les garde-fous de lui-même. Il détermine si une question est technique ou s’il s’agit d’une demande sur le portfolio avant de répondre. C’est plus qu’une zone de recherche avec un champ de texte. C’est moins qu’un agent entièrement autonome qui pourrait, par exemple, ouvrir un rapport de bug à partir de la question d’un utilisateur.

Les rédacteurs techniques ont besoin de cette distinction aujourd’hui. Comprendre les outils et les agents IA fait partie du métier. Lorsque vous documentez un produit doté d’IA, vous devez savoir où il se situe sur ce spectre. Ensuite, vous devez expliquer aux utilisateurs ce que signifie « IA » dans ce produit, car leurs attentes varient.

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

La génération augmentée par la recherche (RAG) alimente Artie et un nombre croissant d’outils de documentation IA. La RAG contourne une limite fondamentale des grands modèles de langage (LLM). Un modèle s’entraîne sur un jeu de données figé. Votre contenu est absent de ses données d’entraînement.

Une interaction standard avec un LLM se déroule ainsi : l’utilisateur envoie une invite et le modèle génère une réponse à partir de ses données d’entraînement. Cela fonctionne pour les connaissances générales et échoue sur les questions propres à un domaine. Interrogez un modèle de base sur l’API de votre produit : soit il invente une réponse, soit il refuse.

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

1. Traitement de la requête. La couche de récupération convertit la question de l’utilisateur en un plongement vectoriel, une représentation numérique de son sens.
2. Récupération. Le système cherche dans la base de connaissances le contenu dont le sens est proche. Ici, la base de connaissances est un index préconstruit de votre documentation. Le classement repose sur le sens, souvent en complément de correspondances de mots-clés. Des requêtes comme « comment configurer l’authentification ? » et « configurer les identifiants de connexion » renvoient la même page de documentation.
3. Assemblage du contexte. Le système regroupe les documents récupérés, ou des extraits de ces documents, dans une fenêtre de contexte à côté de la question de l’utilisateur et de l’invite système. Le modèle traite ensuite cet ensemble.
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. Dans un système bien réglé, il cite ses sources et reste dans les limites de ce que disent 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épend de l’étape 2. Si la couche de récupération renvoie de mauvais documents ou les classe mal, les capacités du modèle n’y changent rien. Le modèle rédige une réponse plausible et bien structurée à partir du mauvais matériau. Le découpage et le choix du modèle de plongement comptent donc plus que la plupart des équipes ne l’imaginent. Le modèle de génération récolte les compliments, mais la couche de récupération détermine la qualité.

Chez Artie, la base de connaissances est la documentation de ce site. Algolia l’indexe et la récupère. Artie ne couvre que ce qui est documenté ici, ce qui le maintient dans le matériau du site. L’étude de cas explique comment cela se traduit concrètement. La RAG ne rend pas un modèle plus intelligent. Elle le rend plus responsable, parce que chaque réponse se rattache à une source vérifiable.

L’ingénierie des prompts est de la rédaction technique

Le projet m’a appris une chose essentielle. Une invite système est un livrable de rédaction technique.

Une invite système bien rédigée contient les mêmes éléments qu’un guide de style. Vous définissez le public. Vous fixez des règles de ton et de voix. Vous délimitez le périmètre : ce que le système doit traiter et ce qu’il ne doit pas traiter. Vous écrivez des consignes assez précises pour qu’une machine les suive sans jugement humain. Vous ordonnez l’information pour que les règles essentielles priment.

Le travail relève de l’analyse du public et du guide de style. Il relève aussi du plan de contenu.

Le transfert de compétences est presque direct :

• Analyse du public → Routage du public. Les rédacteurs techniques identifient le public et adaptent le contenu, et une invite système fait de même pour une IA. L’invite d’Artie sépare les utilisateurs techniques des recruteurs, comme un site de documentation bien structuré sépare les profils de lecteurs.
• Guide de style → Calibrage du persona. Chaque équipe de documentation dispose de règles de voix et de ton. Une invite système est un guide de style pour une IA. Elle ajuste le ton selon le public et exige un lien vers la source pour chaque affirmation.
• Architecture de l’information → Hiérarchie des consignes. Les rédacteurs techniques savent que l’ordre et la structure influencent la compréhension. La place d’une consigne change la façon dont le modèle la respecte.
• Documentation des cas limites → Conception des garde-fous. Une bonne documentation couvre l’action inattendue avec des consignes claires. Une bonne conception d’invite couvre l’utilisateur qui tente de contourner le système.

Tout rédacteur technique n’a pas besoin de devenir ingénieur en prompts. La discipline emprunte des compétences que les rédacteurs techniques développent depuis des décennies. Si vous savez rédiger un document clair, structuré et adapté à son public, vous apportez plus à ce travail que vous ne le pensez.

Les garde-fous sont un problème de langage

Les gens traitent la sécurité de l’IA comme un problème technique : limitation du débit, authentification, contrôles d’accès. Tout cela compte. Dans un chatbot public, une bonne part de ce que visent les attaquants est linguistique.

info

L’injection d’invite se produit lorsqu’un utilisateur outrepasse l’invite système. Un exemple courant est la phrase « ignore toutes les instructions précédentes ».

L’injection d’invite utilise des mots pour contourner des contrôles fondés sur des mots. La défense consiste à écrire des règles assez claires pour qu’un attaquant ne puisse pas convaincre le modèle de les ignorer.

La liste des dix principaux risques pour les applications LLM de l’Open Worldwide Application Security Project (OWASP) classe l’injection d’invite au premier rang. Parcourez cette liste et vous verrez combien de risques sont, à la base, des problèmes de langage :

• Gestion inappropriée des sorties (ce que le modèle produit)
• Empoisonnement des données et des modèles (ce que le modèle a appris du texte)
• Autonomie excessive (ce que l’invite dit au modèle qu’il peut faire)

Les attaques sont techniques. Les défenses sont souvent du langage naturel, écrit dans l’invite système.

Cela redéfinit le travail de sécurité pour les rédacteurs techniques. Personne n’attend de nous que nous construisions des systèmes d’authentification. Mais nous pouvons écrire les règles qui définissent la réponse d’une IA. Nous pouvons les écrire avec assez de précision pour résister à une entrée hostile.

Ce qui change pour le travail de documentation

Je ne vais pas prédire l’avenir de l’IA. Je peux décrire la trajectoire visible aujourd’hui et ce qu’elle signifie pour celles et ceux qui documentent des logiciels pour vivre.

Les assistants de documentation IA sont passés de la nouveauté à l’attente. Les utilisateurs n’acceptent plus une recherche statique. Ils veulent poser une question simple et obtenir une réponse étayée plutôt que dix liens bleus. Les systèmes RAG le permettent dès maintenant. Les outils sont de plus en plus faciles à adopter.

astuce

Vous vous intéressez à l’infrastructure ? La documentation sur les flux d’événements et les pipelines d’observabilité montre comment Datadog et Galileo suivent les appels aux modèles.

Le rôle du rédacteur technique s’élargit au lieu de se réduire. Quelqu’un doit tenir la base de connaissances dans laquelle ces systèmes puisent. Quelqu’un doit écrire les invites système qui définissent comment ils répondent et où ils s’arrêtent. Quelqu’un doit vérifier si les réponses correspondent à la documentation. Tout cela est du travail de rédaction, et cela demande un jugement sur la façon dont les gens consomment l’information.

Les rédacteurs techniques devraient apprendre le fonctionnement des LLM et des systèmes RAG. Nous ne devons pas devenir ingénieurs en apprentissage automatique, mais nous devons participer aux discussions sur les produits IA. Nous avons besoin d’une connaissance suffisante du pipeline pour savoir où notre expertise s’applique et où elle ne s’applique pas.

Les rédacteurs techniques écrivent déjà pour des publics multiples. Ils structurent le contenu et délimitent le périmètre. Ils anticipent les mauvais usages. Ces compétences s’appliquent directement au travail sur l’IA.

L’IA ne remplacera pas les rédacteurs techniques. Les modèles progressent chaque année en génération de texte, mais quelqu’un décide encore quoi dire, à qui, et dans quelles limites.

Ils ont besoin d’un éditeur. C’est nous, les éditeurs.

Rédiger soi-même le premier brouillon fonctionne aussi. Confiez-le à l’agent IA comme relecteur et contrôleur de style.

La façon dont vous utilisez l’IA dans votre flux de travail vous appartient, comme tout autre outil à notre disposition.

Le métier ne change pas. Les outils changent. Le travail ne disparaît pas. Les équipes qui se séparent de leurs rédacteurs techniques finissent par les rappeler.

Lire l’étude de cas

Si cet article vous a donné le « pourquoi c’est important » et le « comment ça marche », lisez l’étude de cas. Elle détaille les décisions de conception propres à Artie :

• Routage du public
• Ancrage des connaissances
• Calibrage du persona
• Garde-fous de sécurité
• Choix que je reconsidérerais pour un déploiement en production

Chaque texte fonctionne seul. Commencez par celui qui vous attire.