Une doc que ton agent peut lire : pourquoi le centre d’aide de Notis tourne sur Mintlify

Voici une question qui n’existait pas il y a cinq ans : un agent IA peut-il lire ta documentation ?

Pas « est-elle sur internet ». Un modèle peut-il la récupérer, l’analyser et donner une réponse exacte à un utilisateur, sans humain dans la boucle ? Parce que pour un produit comme le nôtre, c’est de plus en plus comme ça que les gens découvrent la doc : via un assistant, pas via une barre de recherche.

Le centre d’aide de Notis tourne sur Mintlify, et ça s’est révélé important pour d’autres raisons que son joli rendu.

La doc gérée comme du code, parce qu’elle change aussi vite que le code

Notis livre en permanence. De nouveaux canaux, de nouveaux outils, de nouvelles intégrations, de nouveaux comportements de l’agent. Chacun a une conséquence sur la documentation, et cette conséquence tombe en même temps que le changement, pas lors d’un sprint de contenu deux semaines plus tard.

Avec Mintlify, le centre d’aide est un ensemble de fichiers MDX dans un dépôt, avec un docs.json qui définit la navigation. Les changements de documentation arrivent donc comme les changements de code : dans une branche, dans un diff, relisibles, réversibles.

L’effet pratique, je ne l’avais pas prévu. Un agent de code peut mettre à jour la doc. Quand je confie une tâche à un agent et que cette tâche modifie un comportement visible par l’utilisateur, mettre à jour le fichier .mdx concerné fait partie du même travail que modifier le code. C’est une modification de fichier dans un dépôt auquel il a déjà accès. Si le centre d’aide vivait dans un CMS séparé derrière une connexion, ce serait un deuxième système, un deuxième identifiant et, soyons réalistes, une étape qu’on saute.

Une doc qui pourrit, c’est presque toujours un problème de workflow plutôt que de discipline. Mettre la doc dans le dépôt règle le workflow.

Ce qu’on a vraiment construit avec

Notre centre d’aide n’est pas une liste de fonctionnalités. Il est organisé selon ce que la personne essaie de faire : démarrer, canaux, capacités principales, ton ordinateur, routage des agents, Apps, compte et paramètres, plus une grosse section de guides pour les workflows de bout en bout.

C’est cette section de guides que je mettrais en avant. Notis se connecte à beaucoup d’autres outils, donc une bonne partie de notre documentation consiste à dire « voici comment brancher ce produit précis à Notis, et ce que tu y gagnes ». Chaque guide est une page autonome, avec les prérequis, les étapes de configuration numérotées, des exemples de prompts et une section de dépannage.

Les composants de Mintlify font là un vrai travail. Les astuces et encadrés séparent « tu dois faire ça » de « ça pourrait te plaire ». Les blocs de code contiennent les URL de serveur et les valeurs d’en-tête exactes que les gens collent. Les vidéos intégrées apparaissent là où une démonstration aide plus que du texte. Rien d’exotique, mais tout construire soi-même, c’est une semaine que je préfère passer ailleurs, et le maintenir, c’est pour toujours.

Les pages ont un champ lastUpdated, ce qui a l’air anodin et ne l’est pas. Pour un guide d’intégration, « quand est-ce que ça a été vérifié pour la dernière fois », c’est souvent l’information la plus importante de la page.

La lisibilité par l’IA

Revenons à la question du début.

Une part importante et croissante du trafic qui arrive sur la documentation n’est pas une personne qui navigue. C’est un modèle qui récupère une page pour répondre à la question de quelqu’un, dans ChatGPT, dans Claude ou, dans notre cas, dans Notis lui-même, parce que les utilisateurs demandent à l’assistant comment fonctionne l’assistant.

Ça change la définition d’une bonne doc. La structure l’emporte sur le style. Une page avec des titres propres, des prérequis explicites et des valeurs littérales dans des blocs de code survit à la lecture par un modèle. Une page dont le sens dépend de la mise en page, de captures d’écran ou d’une hiérarchie visuelle astucieuse, non.

Mintlify produit du HTML propre, rendu côté serveur et structuré sémantiquement. Ce n’est pas un argument marketing : c’est ce qui permet au contenu de survivre à l’extraction. Et comme il y a du MDX en dessous, la source est déjà dans le format que les modèles gèrent le mieux.

La version honnête : je n’ai pas d’étude d’attribution qui prouve combien de conversions commencent dans une réponse d’IA. Je peux te dire que c’est une part croissante de la façon dont les gens découvrent la documentation, et que le moyen le moins cher d’être représenté fidèlement, c’est de publier du contenu structuré, à jour et vérifiable. La doc gérée comme du code rend le « à jour » atteignable. Un rendu propre rend « extractible » gratuit.

Les compromis

Il y en a deux, et ils sont bien réels.

Il te faut des gens à l’aise avec Git. Pour nous, ce n’est pas un sujet : c’est le même dépôt, et les agents peuvent le modifier. Pour une équipe dont la documentation est rédigée par des gens qui n’ont jamais ouvert un terminal, un CMS hébergé peut vraiment être le meilleur outil. Choisis le workflow que tes rédacteurs utiliseront vraiment.

Tu dépends de la couche de rendu de quelqu’un d’autre. Les thèmes, les composants et le comportement de la recherche leur appartiennent. Il nous est arrivé de vouloir une chose qui n’existait pas. La question en retour est toujours la même : est-ce que j’ai envie de posséder un site de documentation sur mesure pendant les cinq prochaines années ? Non.

Mintlify héberge notre centre d’aide et on ne s’en cache pas : la mention est visible sur le site plutôt que planquée dans un coin.

Si tu mets en place la doc d’un produit à l’ère de l’IA

1. Mets-la dans le dépôt. C’est la décision qui a le plus d’impact, parce qu’elle fait de la mise à jour de la doc une partie de la livraison.
2. Organise-la selon l’intention de l’utilisateur, pas selon ton architecture interne. Personne ne cherche « le module webhooks ».
3. Écris pour l’extraction. De vrais titres, des prérequis explicites, des valeurs littérales dans des blocs de code, aucun sens porté uniquement par des images.
4. Date tes pages d’intégration. Un guide sur le produit de quelqu’un d’autre est une denrée périssable.
5. Laisse tes agents écrire la doc. Si mettre à jour une page revient à modifier un fichier, ça se fait. Si c’est un système à part, ça ne se fait pas.

Notis est mené par son fondateur et avance vite, ce qui veut dire que notre centre d’aide est en modification permanente. Il suit le rythme parce qu’il vit là où vit le code.

Mintlify est ce qui rend cette configuration agréable plutôt que d’en faire un projet parallèle.