Docs en tant que code vs une plateforme gérée : le compromis de 2026
"Docs en tant que code" — votre documentation vit dans Git, est examinée via des demandes de tirage, déployée via CI — est le modèle dominant dans les entreprises dirigées par l'ingénierie. "Plateforme gérée" — vous vous connectez, configurez et expédiez — est le modèle dominant dans les entreprises axées sur le design et les entreprises indépendantes. Les deux fonctionnent. Les deux échouent de différentes manières.
C'est le compromis honnête en 2026.
TL;DR#
| Docs en tant que code | Plateforme gérée | |
|---|---|---|
| Où vivent les docs | Git | DB de la plateforme ou Git |
| Édition | Markdown dans l'IDE, révision de PR | Éditeur web ou markdown |
| Déploiement | Pipeline CI/CD | Pousser et oublier |
| Hébergement | Le vôtre | Leur |
| Maintenance | Vos heures d'ingénierie | Heures du fournisseur |
| Fonctionnalités AI | Vous construisez ou intégrez | Intégré |
| Forme des coûts | Heures d'ingénierie | Abonnement |
| Meilleur pour | Dirigé par l'ingénierie, OSS, personnalisation approfondie | Startups, indépendant, "expédier maintenant" |
Docsbook est intéressant car il est à la fois : fichiers source dans Git (votre dépôt), tout le reste géré.
Quand "docs as code" gagne#
Trois raisons pour lesquelles docs-as-code est toujours le bon modèle :
1. L'ingénierie vit déjà dans Git#
Si vos rédacteurs de documentation sont des ingénieurs, la charge cognitive d'utilisation de Git pour la documentation est nulle. Les demandes de tirage, la révision de code, les aperçus de branche — tout le flux de travail d'ingénierie existant s'étend naturellement.
2. La versionnage s'aligne avec les versions du code#
Les modifications de documentation qui sont livrées avec des modifications de code doivent figurer dans la même PR. Les réviseurs voient le changement d'API et le changement de documentation ensemble. CI teste les deux.
3. Une personnalisation importante est nécessaire#
Si vos documents nécessitent des composants React, des extensions Markdown personnalisées ou un pipeline de construction qui génère des pages à partir de votre spécification OpenAPI, docs-as-code avec Docusaurus, Nextra ou VitePress est le bon modèle.
Quand la "plateforme gérée" gagne#
Trois raisons pour lesquelles la gestion gagne :
1. Les rédacteurs de documentation ne sont pas des ingénieurs#
Les responsables marketing produit, les membres de l'équipe de support et les responsables du service client doivent souvent mettre à jour la documentation. Leur demander de soumettre un PR markdown à un dépôt Git crée des frictions qui empêchent les mises à jour. Un éditeur web est plus rapide.
2. Les fonctionnalités d'IA sont nécessaires et votre équipe ne les construira pas#
Une plateforme gérée qui propose un chat IA, une traduction IA, MCP, llms.txt et des analyses vous offre chacun de ces éléments comme un interrupteur plutôt que comme un projet. Chacun est un véritable projet si vous le construisez : récupération, une boucle d'évaluation, un pipeline de traduction avec routage par locale, un magasin d'événements. La plupart des équipes ne peuvent justifier aucun de ce travail spécifiquement pour la documentation.
3. La propriété du déploiement est une surcharge, pas une valeur#
Le travail récurrent sur un site de documentation auto-hébergé est réel mais non planifié : migrations de version majeure, dérive des dépendances et de la version de Node, échecs de construction que personne ne gère, recherche nécessitant une nouvelle approbation ou un nouvel hébergement. Rien de tout cela n'expédie quoi que ce soit qu'un lecteur puisse voir.
Évaluez-le à partir de votre propre dépôt plutôt qu'à partir d'une moyenne : comptez les commits dans votre infrastructure de documentation au cours des quatre derniers trimestres qui n'ont changé aucun contenu. Ce nombre est ce qu'une plateforme gérée supprime.
Le hybride : Docsbook#
Docsbook est inhabituel car il ne s'intègre pas proprement dans l'une ou l'autre catégorie.
- La source de vérité est votre dépôt GitHub (propriété docs-as-code)
- Hébergement, IA, recherche, traductions, analyses, MCP sont gérés (propriété managed-platform)
- Pas de pipeline CI/CD, pas de
docusaurus.config.js, pas de swizzle (propriété managed-platform) - Les PR et les revues fonctionnent de la même manière (propriété docs-as-code)
- Pas de verrouillage fournisseur — vos fichiers restent sur GitHub lorsque vous partez (propriété docs-as-code)
Ce modèle est important car les modes de défaillance des docs-as-code purs (fardeau de déploiement) et des gérés purs (verrouillage fournisseur) s'annulent.
Mathématiques des coûts#
Comparons le coût total de possession sur 24 mois pour une startup typique de 5 ingénieurs.
Documentation pure en tant que code (Docusaurus sur Vercel)#
| Élément de ligne | Coût sur 24 mois |
|---|---|
| Hébergement sur un niveau payant | Une facture récurrente que vous ne remarquerez pas |
| Configuration initiale | Heures d'ingénierie, une fois |
| Migrations de version majeure | Heures d'ingénierie, environ deux fois sur deux ans |
| Maintenance trimestrielle | Heures d'ingénierie, récurrentes, non planifiées |
| Création de chat AI | Semaines d'ingénierie, plus la propriété continue de la qualité de récupération |
| Exploitation du chat AI | Stockage vectoriel, embeddings et appels de modèle, mensuel |
| Recherche (Algolia DocSearch, ou auto-hébergé) | Gratuit si approuvé, sinon un abonnement ou plus d'heures |
| Pipeline de traduction | Généralement ignoré, car il s'agit d'un projet plutôt que d'un élément de ligne |
Le côté géré#
| Élément de ligne | Coût sur 24 mois |
|---|---|
| Abonnement ou utilisation mesurée | Le numéro du fournisseur — consultez sa propre page de tarification |
| Configuration initiale | Moins d'une heure |
| Maintenance | Aucune |
Comment exécuter réellement cette comparaison#
Remplissez les deux tableaux avec vos propres chiffres plutôt qu'avec les nôtres. Nous ne publions délibérément aucun chiffre en dollars ici, car les seuls chiffres honnêtes sont les vôtres : votre niveau d'hébergement, le coût chargé de vos ingénieurs, votre trafic.
Deux choses valent la peine d'être remarquées une fois que vous les avez remplies. Tout d'abord, les heures d'ingénierie dominent la colonne auto-hébergée, et ce sont les entrées pour lesquelles personne ne budgète. Deuxièmement, la ligne de traduction est presque toujours vide du côté auto-hébergé — non pas parce que la traduction n'a pas de valeur, mais parce qu'elle ne franchit jamais la barre en tant que projet, ce qui signifie que la comparaison n'est pas équivalente à moins que vous ne le disiez à voix haute.
(Docsbook a précédemment vendu un plan PRO à vie unique ; il n'est plus proposé, et les acheteurs à vie existants conservent leurs conditions d'origine.)
Lorsque le calcul des coûts s'inverse#
Trois scénarios où les docs-en-code sont moins chers :
- Les heures d'ingénierie sont gratuites — vous avez un ingénieur spécifiquement chargé de la plateforme de documentation ; son salaire est engagé de toute façon
- OSS avec des contributeurs de la communauté — les PR de la communauté absorbent la charge de maintenance
- Composants React personnalisés dans les docs — vous ne pouvez pas faire cela sur des plateformes gérées
Pour ces cas, Docusaurus ou VitePress est la bonne réponse. Sinon, les calculs favorisent les gérés.
Verrouillage par le fournisseur : comment évaluer#
Trois questions à poser à toute plateforme gérée :
- Puis-je exporter mon contenu en markdown brut dès maintenant ? Si oui, le verrouillage est faible.
- Les URL survivront-elles si je déménage ? La plupart permettent la préservation des URL ; certaines ne le font pas.
- Que se passe-t-il pour mon domaine personnalisé si j'annule ? Il devrait être récupérable.
Docsbook obtient de bons résultats sur les trois : les fichiers sont dans votre dépôt GitHub (export = git clone), les URL correspondent aux chemins de fichiers (préserver = redirections), le domaine personnalisé est un enregistrement DNS que vous contrôlez.
GitBook obtient de mauvais résultats sur le premier (contenu dans leur base de données), de bons résultats sur les autres. Mintlify obtient de bons résultats sur les trois.
Règles de décision#
- Ingénierie dirigée, OSS, personnalisation importante → docs en tant que code (Docusaurus, VitePress, Nextra)
- Indépendant, startup, "expédier maintenant" → plateforme gérée (Docsbook, Mintlify)
- Entreprise avec 30+ éditeurs → entreprise gérée (GitBook)
- Vouloir le hybride → Docsbook (source Git, tout le reste géré)
Lectures connexes#
- Meilleures plateformes de documentation pour les startups en 2026
- Docusaurus vs Docsbook en 2026
- Comparaison des hébergements de documentation gratuits
Docsbook est l'hybride : la source reste dans Git, tandis que l'IA, le SEO, les traductions et le MCP sont gérés. La tarification est basée sur l'utilisation de l'IA plutôt que vendue par niveau — chiffres actuels sur docsbook.io/pricing.