Docsbook
Aperçu

Pourquoi nous avons arrêté d'utiliser Notion pour la documentation produit

J'avais l'habitude de tout mettre dans Notion. Manuel interne, spécifications produit, FAQ à destination des clients, exemples d'API, le guide de fonctionnement pour la rotation d'astreinte, le journal des modifications, le guide d'intégration à moitié terminé que personne n'a lu. Un espace de travail, une boîte de recherche, un ensemble de permissions. C'était génial pendant environ dix-huit mois.

Ensuite, nous avons essayé d'augmenter le trafic vers la documentation. Puis nous avons essayé d'ajouter une deuxième langue. Et ensuite, un client a demandé pourquoi la page qu'il lisait était trois versions en retard par rapport à l'API. Au moment où j'ai migré tout hors de Notion, j'avais une liste d'erreurs que j'aurais aimé que quelqu'un me remette dès le premier jour.

C'est cette liste. Ce n'est pas une critique — Notion est un produit vraiment bon pour ce pour quoi il est conçu. C'est un article sur le moment précis où "bon wiki" cesse d'être "bonne documentation", et comment remarquer ce moment avant d'avoir 400 pages et une équipe de vente qui a besoin que la documentation soit réellement référencée.

Où Notion gagne-t-il encore ?#

Avant les plaintes, la partie honnête.

Notion est le meilleur outil que j'ai utilisé pour la réflexion collaborative. Documents stratégiques, notes de réunion, RFC en brouillon, spécifications de produit discutées par quatre personnes dans les commentaires — Notion est la bonne réponse. Le modèle de blocs, les vues de base de données, les bases de données en ligne, les mentions liées, le fait que quiconque non technique puisse éditer sans rien casser — tout cela est réel et difficile à reproduire.

Si vos documents vivent entièrement au sein de l'entreprise et n'ont jamais à rivaliser pour l'attention d'un étranger sur Google, Notion est bien. Si votre audience est de quarante personnes qui ont toutes votre identifiant Notion, ce post ne s'applique pas à vous. Fermez l'onglet et allez écrire quelque chose d'utile.

Le reste de ce post concerne le moment où les documents quittent le bâtiment.

1. La recherche est deux problèmes différents et Notion en résout un#

La recherche interne de Notion est excellente. Cmd+K, correspondance floue à travers les titres, accès direct à la page. C'est la recherche qui intéresse les ingénieurs, et Notion l'a bien construite.

La recherche qui intéresse les clients se trouve sur Google, ChatGPT et Perplexity. Et sur cette recherche, Notion est hostile par défaut. Les pages se chargent via JavaScript, le HTML est principalement vide jusqu'à ce que React hydrate, les liens internes passent par notion.so/<hash> redirections, les titres sont souvent rendus avec un balisage non sémantique, et les URL ressemblent à notion.site/Getting-Started-9f8a3b2c1d4e. Google peut l'explorer, mais le résultat SEO est systématiquement pire que le même contenu en markdown simple sur un domaine normal.

La première fois qu'un concurrent avec un contenu objectivement moins bon nous a surpassés parce qu'il a écrit en markdown et expédié un plan de site, j'ai compris la leçon. Les documents destinés aux clients sont une surface SEO. Ils doivent être traités comme telle. Un wiki n'est pas une surface SEO.

2. Contrôle de version qui n'est pas un contrôle de version#

Notion a un historique des pages. Ce n'est pas git. La différence compte plus que je ne l'avais prévu.

Je ne peux pas comparer deux versions d'un document lors d'une révision de code. Je ne peux pas demander "qu'est-ce qui a changé dans la section auth entre v1.4 et v1.5 ?" et obtenir une réponse claire. Je ne peux pas mettre un changement de docs dans la même demande de tirage que le changement de code qu'il documente, donc les docs sont toujours légèrement en retard. Je ne peux pas demander à un ingénieur junior de mettre à jour la référence API dans le cadre de la même PR qui expédie l'API, car les docs vivent dans un système différent avec des permissions différentes et un modèle mental différent.

Le résultat est un décalage de documentation. Le code est expédié lundi, le doc est mis à jour jeudi, et mercredi un client lit l'ancienne version et dépose un ticket de support. Multipliez par chaque version. La solution n'est pas "rappeler aux gens de mettre à jour Notion". La solution est de mettre les docs à côté du code, afin que "le code a été expédié mais les docs ne l'ont pas été" soit quelque chose que l'outil de diff peut vous signaler.

Une fois que j'ai eu des docs dans un dépôt avec des modèles de PR, les mises à jour de docs ont commencé à faire partie de la définition de fait, et non d'une réflexion après coup. Ce changement de flux de travail unique a fait plus pour la fraîcheur des docs que n'importe quel outil.

3. Le multilingue n'est pas une fonctionnalité, c'est une architecture#

Nous avons essayé d'internationaliser nos documents Notion une fois. Le plan était raisonnable : dupliquer l'espace de travail, traduire, lier à partir d'un sélecteur de langue. En un mois, c'était ingérable.

Le véritable coût des documents multilingues n'est pas la traduction. C'est le couplage entre les langues. Lorsque la version anglaise change, chaque traduction est désormais obsolète, et vous avez besoin d'un système qui le sache. Vous avez besoin de :

  • Une source canonique afin que les traducteurs sachent de quelle version ils traduisent.
  • Un moyen de marquer une traduction comme obsolète lorsque la source évolue.
  • hreflang tags pour que Google sache que la page espagnole est la version espagnole de la page anglaise, et non un duplicata.
  • Une URL par langue avec des chemins prévisibles (/es/getting-started, /de/getting-started).
  • Un moyen de publier une traduction partielle — certaines pages en cinq langues, d'autres en deux — sans casser la navigation.

Notion ne fait rien de tout cela. Vous vous retrouvez avec cinq espaces de travail déconnectés et une feuille Google pour suivre ce qui est devenu désynchronisé. La feuille Google fonctionne pendant environ trois semaines, puis tout le monde abandonne.

Si vous prévoyez un jour de publier des documents dans plus d'une langue, ne commencez pas avec Notion. Le coût de migration augmente linéairement avec le nombre de pages et la douleur augmente de manière superlinéaire.

4. Les crawlers IA ne peuvent pas lire votre wiki#

C'est le nouveau, et celui que j'ai sous-estimé.

En 2026, une part significative des questions "comment fonctionne X" n'atteindra jamais votre site web. L'utilisateur demande à ChatGPT, Claude ou Perplexity, et la réponse est synthétisée à partir de ce que ces modèles peuvent voir. Mintlify a mesuré 30 jours de trafic sur les sites de documentation qu'il héberge — environ 790 millions de requêtes — et a rapporté que les agents de codage IA représentaient 45,3 % de toutes les requêtes, avec Claude Code à 25,2 % et Cursor à 18,0 % (L'état du trafic des agents dans la documentation, publié le 3 avril 2026). Sa mesure de suivi a placé la part des agents à 66 % du trafic en juillet 2026 (rapport de mi-année 2026, publié le 29 juillet 2026). C'est la flotte d'un fournisseur plutôt que l'ensemble du web, mais c'est la plus grande mesure publiée du trafic des agents vers la documentation. Nos propres chiffres sont plus petits et vont dans la même direction.

Pour qu'un crawler IA cite vos docs, il doit être capable de lire vos docs. Cela signifie un HTML rendu par le serveur propre, des titres sémantiques, un sitemap.xml, idéalement un llms.txt listant le contenu canonique, et un Allow pour les principaux agents utilisateurs IA dans robots.txt. Notion ne vous en donne presque aucun. Le HTML est lourd en JavaScript, il n'y a pas de llms.txt, et le taux de réponse des crawlers IA est empiriquement faible.

Si vous voulez être cité dans un moteur de réponse, vos docs doivent ressembler, pour un crawler, à un site de documentation. Ils ne peuvent pas ressembler à une SPA construite autour d'une vue de base de données.

5. Le budget de performance pour les docs est brutal#

Une page de docs devrait sembler instantanée. Ce n'est pas une préférence stylistique — c'est un levier de conversion. L'utilisateur débogue à 2h du matin, il est déjà frustré, chaque seconde de temps de chargement est une chance pour lui d'abandonner et de soumettre un ticket à la place.

Faites passer une page publiée sur Notion par Lighthouse. Les chiffres ne sont pas excellents. Le Largest Contentful Paint est généralement dans la plage de 3 à 5 secondes sur une connexion cellulaire réelle, le Cumulative Layout Shift est perceptible car l'arbre React se hydrate par vagues, et le Total Blocking Time est élevé car il y a beaucoup de JavaScript à analyser.

Pour un wiki interne, personne ne s'en soucie. Pour un document destiné aux clients qui doit rivaliser avec mille autres onglets que l'utilisateur a ouverts, cela compte beaucoup. Nous avons constaté une baisse significative du taux de rebond sur les pages de docs lorsque nous sommes passés à du markdown rendu statiquement. C'est l'un de ces chiffres que, une fois que vous l'avez vu, vous ne pouvez plus l'ignorer.

6. Le verrouillage est réel et il s'accumule#

Notion a une exportation. Je l'ai utilisée. La sortie est un dossier de fichiers HTML ou markdown avec des noms de fichiers déformés, des liens internes cassés pointant vers notion.so URLs, des bases de données intégrées qui se transforment en tables illisibles, et des références d'images qui pointent vers des URLs S3 signées qui expirent. Exporter 400 pages et ensuite corriger l'exportation prend une semaine de travail.

Le verrouillage ne concerne pas l'existence du bouton d'exportation. Il s'agit de savoir si les données exportées sont suffisamment structurées pour être utiles dans un autre outil sans port. Selon ce critère, les exportations de Notion sont faibles. Plus vous restez longtemps, plus vous accumulez de pages, et plus le coût de migration augmente. Vous ne le remarquez que lorsque vous essayez de partir.

Le markdown dans un dépôt git a la propriété opposée. L'« exportation » est git clone. Vous pouvez déplacer le répertoire vers n'importe quel autre générateur de site statique, n'importe quelle autre plateforme de documentation, ou simplement le publier en tant que fichiers bruts. Cette portabilité est la propriété la plus sous-estimée qu'un système de documentation puisse avoir. Elle ne semble pas précieuse jusqu'au jour où vous en avez besoin, et alors elle vaut tout.

7. Permissions, brouillons et la séparation wiki-docs#

Le problème le plus profond est que les wikis et les docs sont des produits différents qui ont l'air identiques dans l'éditeur.

Un wiki est pour nous. Il a des brouillons, des pages inachevées, des sections réservées à l'interne, des pages où deux responsables d'équipe ne sont pas d'accord dans les commentaires, des runbooks qui ne devraient jamais être publics, et un dossier "archive" qui est en réalité juste un endroit où les choses vont pour être oubliées. Le modèle de permission est granulaire car l'audience est granulaire.

Les docs sont pour eux. Il y a une version publiée, pas d'états intermédiaires, pas de brouillons visibles pour les lecteurs, et pas de fils de commentaires visibles depuis l'URL publique. Les brouillons vivent dans des demandes de tirage, pas dans l'arbre de production. Le modèle de permission est binaire — publié ou non — car l'audience est l'ensemble d'internet.

Notion est construit pour le premier emploi et patché pour le second. Vous vous retrouvez avec un espace de travail qui mélange des pages de manuel interne et des docs API destinés aux clients dans le même arbre, et une erreur de configuration rend la mauvaise page publique. J'ai vu cela se produire dans trois entreprises, et j'ai failli le faire moi-même.

La frontière entre "wiki" et "docs" mérite d'être rendue physique. Système différent, dépôt différent, flux de révision différent, domaine différent.

Que utilisons-nous à la place ?#

Pour les choses internes qui nécessitent des commentaires, des opinions, des brouillons et des bases de données en ligne — documents de stratégie, RFC, notes de réunion, le manuel — Notion est toujours le bon outil. Nous n'avons pas arrêté d'utiliser Notion. Nous avons cessé de l'utiliser pour le mauvais travail.

Pour la documentation destinée aux clients, les docs se trouvent dans un dépôt git, écrits en markdown, examinés via des pull requests, publiés en tant que site statique. La configuration est ennuyeuse par choix. Les docs sont à côté du code, donc ils se mettent à jour dans le même PR. L'historique git est l'historique des versions. Le dépôt est l'exportation. Le CI effectue des vérifications de liens. Le site publié est rendu côté serveur avec des titres appropriés, un plan du site, un llms.txt, et une URL par langue.

Que vous utilisiez Docsbook, Docusaurus, Mintlify, VitePress, ou que vous créiez le vôtre avec eleventy est une décision moins importante qu'elle n'en a l'air. La plus grande décision est celle d'avant : ces docs sont-ils pour l'équipe, ou sont-ils pour le monde ? S'ils sont pour le monde, sortez-les du wiki et mettez-les dans un système qui les traite comme un produit.

Nous avons construit Docsbook parce que nous voulions que "dépôt git de markdown" soit à cinq secondes de "site de documentation publié avec SEO, chat AI, quinze langues et analyses" — sans un seul pas de CI ou docusaurus.config.js. C'est la version de cette histoire où nous avons un produit à vendre. C'est aussi le chemin honnête que nous avons emprunté. Nous avons d'abord essayé Notion. Nous avons ensuite essayé Docusaurus. Nous avons fini par écrire Docsbook parce que nous voulions la simplicité de Notion avec les propriétés d'ingénierie d'un vrai site de docs, et personne d'autre ne l'avait construit.

Le seul principe à garder#

Si vos documents doivent être trouvés par des personnes qui ne travaillent pas dans votre entreprise, ils sont un produit de référencement et de découvrabilité par l'IA. Traitez-les comme tel. Mettez-les dans le contrôle de version, rendez-les en HTML, donnez à chaque langue une véritable URL, et assurez-vous qu'un robot puisse les lire sans exécuter votre JavaScript.

Un wiki est pour les personnes qui sont déjà à l'intérieur. Les documents sont pour les personnes qui sont encore à l'extérieur, regardant à l'intérieur. Vous avez une seule chance de faire cette première impression, et cela se produit généralement à 2 heures du matin, sur un téléphone, alors que le lecteur est agacé. Construisez pour ce lecteur, pas pour la réunion où le document a été écrit.

C'est la leçon. Tout le reste est un détail d'implémentation.

Commencez gratuitement — pas de carte de crédit

Étapes suivantes#

Updated

Cette page vous a-t-elle été utile ?

Propulsé par Docsbook