Checklist des critères non négociables pour remplacer Mintlify

💡

Refusez un outil qui oblige l’équipe à sortir du flux Git pour modifier une doc versionnée. Une modification doit partir en branche, passer en PR, déclencher la CI et laisser un diff lisible; ce modèle correspond au fonctionnement docs-as-code décrit pour Docusaurus (source: Docusaurus documentation (consulted 2026-06)).

Markdown ou MDX garde la documentation proche du code: revue par PR, historique Git, owners par dossier et checks automatisés. Un éditeur WYSIWYG reste acceptable s’il exporte un format texte contrôlable et relisible hors plateforme.

La recherche doit indexer les espaces privés sans exposer leur contenu à des utilisateurs non autorisés. Les logs de requêtes doivent montrer les recherches sans résultat, les formulations fréquentes et les contenus qui répondent mal.

Vérifiez le support des branches, des versions publiées et des prévisualisations sur PR. Le rollback doit restaurer une version stable sans reconstruire manuellement l’arborescence, les assets ou les liens internes.

Pour des docs internes, exigez SSO, groupes, rôles granulaires et espaces privés séparés. Un espace client, une base interne et une doc publique ne doivent pas partager les mêmes droits par défaut.

Le remplaçant doit conserver les URL utiles, produire un sitemap, gérer les canonical et prévoir des redirections permanentes pour les pages déplacées. Les templates doivent être testés sur performance, rendu mobile et stabilité des métadonnées.

Arbre de décision: open source (Docusaurus) ou SaaS (GitBook/Mintlify)

Option	Quand la choisir	Point de vigilance
Docusaurus	Docs-as-code: contenu en Markdown/MDX, versionné dans Git, build statique via CI (source: Docusaurus documentation (consulted 2026-06)).	Vous opérez l’hébergement, la recherche, les previews et les redirections.
GitBook	Équipe produit, support ou CS très présente: édition hébergée, collaboration et permissions packagées (source: GitBook Pricing page (consulted 2026-06)).	La facturation et les options doivent être vérifiées avant cadrage budgétaire.
Mintlify	Docs avec composants MDX et génération assistée pour publier vite (source: Mintlify Pricing page (consulted 2026-06)).	La vitesse initiale peut coûter en personnalisation et en dépendance fournisseur.

Décision principale

Choisissez Docusaurus si vos docs suivent déjà le cycle pull request, review, CI et release. Le contrôle Git rend les changements auditables, reproductibles et faciles à relier au code applicatif.

Choisissez GitBook si les contributeurs non-tech écrivent souvent: PM, support, success ou marketing produit. Un éditeur WYSIWYG réduit le besoin de connaître MDX, Git et les conflits de merge.

Choisissez Mintlify si la priorité immédiate est de sortir une documentation moderne avec composants MDX et assistance de génération. Validez avant achat ce qui reste exportable sans perte.

Critère anti-lock-in

Le critère bloquant n’est pas le thème: exigez un export Markdown complet, avec assets, slugs et métadonnées, ainsi qu’une gestion explicite des redirections. Sans ces éléments, chaque changement d’outil devient une migration manuelle.

Si l’équipe produit écrit beaucoup, privilégiez WYSIWYG, permissions fines et workflow de validation. Si l’équipe engineering possède la doc, gardez le docs-as-code: moins confortable, mais plus prévisible en revue, rollback et automatisation.

TCO: modèle rapide pour estimer le coût réel de vos docs

Le TCO mensuel tient dans une formule simple: (sièges × prix) + hébergement/CDN + recherche + CI/build + identité/SSO + support/maintenance. Gardez chaque poste séparé, car un forfait bas peut déplacer le coût vers les builds, le support ou l’identité.

Poste	Variable à suivre
Licences	n_seats, profil lecteur/éditeur/admin, options SSO
Build	coût minute de build, fréquence de déploiement, previews par pull request
Diffusion	trafic mensuel, cache CDN, bande passante, stockage d’images
Recherche et IA	indexation, requêtes internes, éventuels tokens IA
Maintenance	temps d’équipe, incidents, mises à jour du thème

Ajoutez une ligne “migration” hors run mensuel. Elle couvre le mapping d’URL, les redirections permanentes, les changements de frontmatter, les scripts de conversion et les tests de liens internes.

💡

Un coût caché se mesure en heures d’équipe: maintien du thème, revue des composants MDX/MDC, formation des éditeurs et accompagnement des contributeurs non techniques.

Budgétez aussi les risques. Une indisponibilité bloque la consultation des docs. Une régression SEO peut peser sur l’acquisition organique. Une dette de contenus augmente le temps de support. Un plugin propriétaire peut rendre une migration suivante plus coûteuse.

Après la migration, comparez licences utilisées, minutes de build, taux de cache CDN, stockage d’images et consommation IA. Ajustez ensuite sièges, quotas et règles de cache à partir des données observées.

Migration sans casse: plan en 10 jours et points de contrôle

J1–2 — Audit, gel et mapping

Dressez l’inventaire des URL publiques, titres, méta-descriptions, ancres et fichiers médias référencés. Gelez les mises à jour côté docs en verrouillant la branche principale ou en imposant une PR de migration.

Définissez les objectifs SEO avant de toucher au contenu: conserver les slugs utiles, préserver les pages indexées et éviter les doublons. Créez un mapping d’URL avec une colonne source, une colonne cible et un statut de validation.

J3–4 — POC de build, thème et previews

Montez un POC qui compile le dépôt réel, pas un exemple vide. Le thème doit couvrir navigation, table des matières, blocs de code, alertes et pages d’erreur.

Activez les previews sur PR pour relire chaque changement dans son contexte. Lancez les tests d’accessibilité disponibles dans votre pipeline, puis vérifiez les liens internes et externes critiques.

J5–6 — Conversion MD/MDX et assets

Convertissez les fichiers MD/MDX avec une passe automatisée, puis une revue manuelle des composants custom. Les erreurs fréquentes touchent les imports, les tabs, les admonitions et les snippets réutilisés.

Importez images, vidéos et fichiers téléchargeables dans une arborescence stable. Ajoutez des scripts qui échouent le build sur lien cassé, ancre absente ou asset introuvable.

J7–8 — Recherche, sitemap et staging

Configurez la recherche sur le contenu final, pas sur le dépôt partiellement migré. Générez les sitemaps et vérifiez les canonical pour éviter deux versions indexables de la même page.

Publiez un staging protégé par mot de passe pour la QA produit, support et engineering. La checklist doit inclure navigation, recherche, rendu mobile, pages profondes et exemples de code.

J9–10 — Cutover, redirections et monitoring

Déployez les redirections permanentes depuis chaque ancienne URL vers sa cible validée. Configurez les headers de cache/CDN avant ouverture publique pour éviter de servir une version obsolète.

Surveillez les erreurs d’accès dès la mise en production avec logs serveur ou analytics. Soumettez le sitemap dans Search Console et demandez la reindexation des pages stratégiques.

Matrice de choix pondérée: template prêt à coller

Attribuez une note à chaque critère, puis multipliez-la par le poids suggéré. Évaluez chaque outil sur le même échantillon: un dépôt réel, avec ses pages, médias, composants et historique de versions.

Critère	Poids suggéré	Épreuve sur repo réel
DX d’édition	25%	Créer, modifier et relire une page sans workflow parallèle.
Versioning/CI	20%	Brancher une PR de doc, une prévisualisation et une publication.
Recherche	15%	Indexer l’échantillon importé et tester requêtes produit, API et erreurs.
SEO/perf	15%	Vérifier slugs, métadonnées, sitemap et rendu mobile.
Sécurité/SSO	10%	Tester rôles, accès privés et authentification d’équipe.
Coût/TCO	15%	Reporter abonnement, maintenance, migration et temps d’équipe.
Risque de lock-in	Arbitrage	Contrôler formats de sortie, composants propriétaires, SLA et portabilité.

Règle d’élimination: excluez tout outil sans export Markdown complet. Écartez aussi tout outil dont les redirections permanentes ne sont pas contrôlables, car la migration SEO devient non vérifiable.

Preuve rapide de faisabilité: importez un échantillon de pages et de versions, activez la recherche, puis faites valider les blocages par le support. Un score élevé sans import réussi ne vaut rien.

Guide pour choisir une alternative à Mintlify sans regret