Guide
Structurer la documentation d'un logiciel pour l'IA
Les quatre types de pages de Diátaxis, un sujet par page, fichier llms.txt : préparer votre documentation pour qu'un assistant y réponde juste.
Mis à jour le
Un assistant d'aide en ligne ne répond jamais mieux que les pages qu'il trouve. Il découpe votre documentation en passages, cherche ceux qui ressemblent à la question, puis rédige à partir d'eux. Une documentation lisible par l'IA est donc d'abord une documentation bien rangée : un sujet par page, des titres qui disent la tâche, les noms exacts des écrans écrits en toutes lettres, et la version ou le forfait concerné indiqué clairement.
Ce qui trompe un assistant
| Défaut fréquent | Ce que fait l'assistant | Correction |
|---|---|---|
| Une page « Paramètres » de 4 000 mots qui traite de tout | Il ramène un passage voisin, pas le bon | Une page par réglage ou par tâche |
| L'information n'est que dans une capture d'écran | Il ne la voit pas | Écrire le chemin : « Réglages > Facturation > TVA par défaut » |
| Deux pages qui décrivent l'ancien et le nouvel écran | Il mélange les deux | Retirer ou marquer l'ancienne page |
| « Cliquez ici » | Il ne sait pas où « ici » mène | Nommer le bouton |
| La fonction dépend du forfait, la page ne le dit pas | Il l'explique à tout le monde | Une ligne « Disponible sur les forfaits… » |
| Des sigles maison jamais définis | Il les recopie ou les devine | Les définir une fois dans la page |
Ranger par type de page : Diátaxis
La méthode Diátaxis, publiée sur diataxis.fr, distingue quatre formes de documentation, qui répondent à quatre besoins différents :
| Type | Définition de Diátaxis | Question type posée à l'assistant |
|---|---|---|
| Tutoriel | « A tutorial is a lesson » : apprendre en faisant, pas à pas | « Comment je démarre avec le logiciel ? » |
| Guide pratique | « Addresses a real-world goal or problem » : atteindre un objectif précis | « Comment j'importe mes clients depuis un tableur ? » |
| Référence | « Contain the technical description » : faits précis, consultés en travaillant | « Quels formats de fichier sont acceptés ? » |
| Explication | « Provide context and background » : le pourquoi | « Pourquoi mes factures sont-elles verrouillées après envoi ? » |
L'intérêt pour un assistant : une page d'un seul type a un seul but. Quand la question est « comment », le guide pratique répond ; quand elle est « quels formats », la référence répond. Une page qui mêle les quatre envoie l'assistant dans tous les sens.
Le titre et la première phrase font le travail
L'assistant choisit ses passages en comparant leur sens à celui de la question. Aidez-le :
- un titre qui reprend les mots de l'utilisateur : « Ajouter un collaborateur » plutôt que « Gestion des accès » ;
- une première phrase qui répond : « Pour ajouter un collaborateur, ouvrez Réglages > Équipe, puis… » ;
- les synonymes que vos clients emploient : si certains disent « salarié » et d'autres « collaborateur », écrivez les deux une fois ;
- les messages d'erreur recopiés tels quels, entre guillemets : les utilisateurs les collent dans leur question.
Dater ce qui change
Les notes de version sont une source précieuse : elles disent depuis quand une fonction existe. Le site keepachangelog.com propose quelques principes simples, pensés pour les lecteurs humains et utiles à un assistant : une section par version avec sa date, la version la plus récente en haut, des changements groupés par catégorie (ajouts, modifications, fonctions bientôt retirées, retraits, corrections, sécurité). Une fonction retirée doit aussi disparaître de la documentation, ou y être signalée comme retirée.
Le fichier llms.txt
Le site llmstxt.org présente une proposition de Jeremy Howard, publiée le 03/09/2024 et modifiée le 10/08/2026 : placer à la racine d'un site un fichier /llms.txt « to help agents use a website ». Le format est du Markdown :
- un titre de premier niveau avec le nom du projet (seule partie obligatoire) ;
- un court résumé en citation ;
- des paragraphes d'explication ;
- des sections de liens vers les pages détaillées, chacun avec une note facultative ;
- une section « Optional » pour ce qu'un agent peut ignorer.
C'est une proposition, pas une norme : rien ne garantit qu'un outil donné le lise. Pour votre propre assistant, il est rarement nécessaire, puisque vous lui donnez directement vos pages. Il sert surtout aux assistants extérieurs qui parcourent votre documentation publique.
La liste de contrôle avant d'indexer
- Chaque page traite d'un seul sujet, d'un seul type
- Les titres reprennent les mots des utilisateurs
- La première phrase répond à la question du titre
- Les chemins de menus sont écrits en texte, pas seulement montrés en image
- Le forfait ou le module concerné est indiqué
- Les pages des anciens écrans sont retirées ou marquées
- Les notes de version sont datées
- Les messages d'erreur fréquents ont leur page
Ensuite, laissez les questions vous guider
Une fois l'assistant en service, ses questions sans réponse deviennent votre liste de pages à écrire ou à renommer : voir l'assistant d'aide en ligne. Pour comprendre ce qu'un assistant fait de ces pages une fois chargées, la base de connaissances d'un chatbot l'explique simplement.
Questions fréquentes
Faut-il réécrire toute la documentation avant de lancer un assistant ?
Non. Commencez par les pages qui répondent aux questions les plus fréquentes de vos tickets, et corrigez au fil des questions sans réponse. Une documentation se reprend par morceaux.
Qu'est-ce que le fichier llms.txt ?
Une proposition de Jeremy Howard, publiée le 03/09/2024 : un fichier Markdown placé à la racine d'un site, avec un titre, un court résumé et des listes de liens, pour aider les agents d'IA à utiliser le site. C'est une proposition, pas une norme.
Les captures d'écran suffisent-elles ?
Pour un humain, souvent. Pour un assistant qui lit du texte, non : le nom du menu, du bouton et du champ doit être écrit dans la page.
Sources
Pages consultées pour écrire cet article :