Comparaison des solutions

Avant de choisir une plateforme documentaire, il est utile d'évaluer les candidats sur un ensemble de critères communs. Cette page presente une grille multi-critères couvrant quatre solutions representatives, puis propose une recommandation argumentee destinée a alimenter un ADR.

Les quatre solutions retenues pour cette comparaison représentent les grandes catégories du marche :

• MkDocs Material : generateur de site statique, ecosysteme Python, approche docs-as-code.
• Docusaurus : generateur de site statique, ecosysteme JavaScript/React, conçu pour les projets open-source.
• Confluence : wiki d'entreprise WYSIWYG, solution commerciale Atlassian, tres repandue dans les grandes organisations.
• BookStack : wiki self-hosted open-source, interface accessible, base PHP/MySQL.

1. Critères de comparaison¶

Les critères retenus couvrent les dimensions techniques, organisationnelles et economiques d'un choix de plateforme documentaire.

2. Grille comparative détaillée¶

Synthese visuelle par axe¶

Trois axes de comparaison se degagent naturellement de la grille :

Axe 1 — Integration dans le cycle de développement¶

MkDocs Material et Docusaurus s'intègrent directement dans un dépôt Git et un pipeline CI/CD. Confluence et BookStack necessitent une synchronisation externe (webhooks, scripts) pour se rapprocher de ce modèle, ce qui ajoute de la complexité sans atteindre le même niveau de traçabilité.

Axe 2 — Accessibilite editoriale¶

Confluence et BookStack ont des interfaces WYSIWYG accessibles a des profils non-techniques (chefs de produit, équipes support, redacteurs). MkDocs Material et Docusaurus requierent une maîtrise minimale de Markdown et de Git, ce qui peut etre un frein dans des organisations a culture documentaire peu developpee.

Axe 3 — Coût total de possession¶

Les generateurs statiques ont un coût d'hebergement quasi nul (CDN, GitHub Pages). Confluence représente le coût le plus eleve (licences + infrastructure). BookStack se situe entre les deux (hebergement self-hosted sans licence, mais maintenance applicative a prevoir).

3. Analyse par solution¶

MkDocs Material¶

MkDocs Material est un generateur de site statique base sur Python. La commande mkdocs build produit un ensemble de fichiers HTML/CSS/JS deployables sur n'importe quel CDN (Cloudflare Pages, GitHub Pages, Netlify) ou serveur web basique. Il n'y a aucun runtime a maintenir en production.

Atouts principaux :

• Integration Git native : les sources Markdown vivent dans le dépôt aux cotes du code, l'historique par commit est automatique, les pull requests permettent de reviser la documentation comme du code.
• Theme Material Design le plus abouti de l'ecosysteme : dark mode, palette CSS personnalisable, navigation avancee (onglets, sidebar, mini-TOC), admonitions, diagrammes Mermaid, coloration syntaxique.
• Ecosysteme de plugins Python etendu : mkdocs-git-revision-date-localized (date de dernière modification), mkdocs-static-i18n (multilingue), mkdocs-awesome-pages-plugin (ordre de navigation automatique).
• Zero runtime en production : pas de serveur applicatif, pas de base de données, pas de processus a surveiller.
• Hebergement gratuit sur GitHub Pages, GitLab Pages ou Cloudflare Pages.

Limites a anticiper :

• Absence d'interface WYSIWYG : les contributeurs non-techniques doivent apprendre Markdown et utiliser Git.
• Confidentialite multi-niveaux non native : restreindre l'accès a certaines pages requiert plusieurs builds distincts (un par audience) ou un plugin de filtrage au moment de la génération.
• Recherche Lunr client-side : efficace jusqu'a plusieurs centaines de pages, mais peut dégrader l'expérience sur de tres grands corpus.

Docusaurus¶

Docusaurus est un framework de documentation base sur React, maintenu par Meta et largement utilise dans les projets open-source (React, Jest, Docusaurus lui-même). La commande yarn build produit des fichiers statiques deployables sur tout CDN, comparable a MkDocs sur ce point.

Atouts principaux :

• Composants React (JSX) intégrés dans les pages : graphiques live, demos de code interactives, custom widgets, sans infrastructure supplémentaire.
• Versioning documentaire natif : versioned_docs/version-x.y/ permet de maintenir plusieurs versions simultanées de la documentation, idéal pour les produits avec des cycles de release fréquents.
• i18n natif : structure de répertoires dédiée et workflow de traduction documente, sans plugin tiers.
• Ecosysteme Meta open-source tres actif, documentation officielle de qualité.

Limites a anticiper :

• Ecosysteme Node.js : dependances node_modules parfois volumineuses, compétences front-end requises pour étendre le framework ou corriger des problèmes de build.
• Format MDX : plus expressif que Markdown pur, mais moins portable — un contenu MDX avec JSX inline ne peut pas etre ouvert directement dans un autre outil documentaire sans retraitement.
• Gestion de permissions non native : comme MkDocs, un développement spécifique ou une couche d'authentification externe est nécessaire.
• Temps de build plus long que MkDocs sur de grands corpus, en raison du transpileur React.

Confluence¶

Confluence est le wiki d'entreprise d'Atlassian, disponible en SaaS (Confluence Cloud) ou en self-hosted (Data Center). C'est la solution la plus repandue dans les grandes organisations, notamment celles déjà equipees de Jira ou Bitbucket.

Atouts principaux :

• Interface WYSIWYG accessible a tous les profils (chefs de produit, équipes support, redacteurs) sans prerequis Markdown ni Git.
• Gestion des permissions native et granulaire : restrictions par espace, par page et par groupe d'utilisateurs, configurables sans développement.
• Moteur de recherche Lucene côté serveur : indexation du texte integral des pages et des attachements, filtres avances par espace, auteur, date.
• Macros riches (tableaux de bord, listes de tâches, diagrammes Confluence) qui etendent les possibilites editoriales sans code.
• Integrations natives avec Jira, Bitbucket et l'ensemble de la suite Atlassian.

Limites a anticiper :

• Licence commerciale par utilisateur : coût potentiellement eleve pour des équipes importantes, vendor lock-in fort.
• Pile technique lourde en mode self-hosted : JVM, base de données PostgreSQL ou MySQL, potentiellement Elasticsearch, effort operationnel notable (mises a jour, sauvegardes, monitoring).
• Absence de versionnement Git : la documentation vit en base de données, hors du dépôt de code, sans historique par commit ni workflow de revue documentaire.
• Export et portabilité limites : migrer hors de Confluence est penible (formats proprietaires, pertes de mise en forme).
• Personnalisation du theme tres contrainte par rapport aux generateurs statiques.

BookStack¶

BookStack est un wiki self-hosted open-source sous licence MIT, developpe en PHP avec le framework Laravel et une base de données MySQL. Son modèle d'organisation hierarchique — Shelves > Books > Chapters > Pages — est intuitif pour des utilisateurs non-techniques.

Atouts principaux :

• Interface simple et intuitive, accessible aux profils non-techniques sans formation spécifique.
• Gestion des rôles et permissions native : droits de lecture, d'edition et d'administration configurables par entite (shelf, book, page) sans développement.
• Licence MIT, hebergement self-hosted : pas de coût de licence, données sous le contrôle total de l'organisation.
• Éditeur supportant le mode Markdown en complement du mode WYSIWYG.

Limites a anticiper :

• Application PHP/MySQL sans site statique : serveur web, base de données et maintenance applicative requis en permanence.
• Absence de versionnement Git natif : les sources ne vivent pas dans un dépôt, il n'existe pas de workflow pull request pour la documentation.
• Extensibilite tres limitee : peu de hooks d'integration, API REST basique, personnalisation du theme en templates Blade plus laborieuse qu'avec Material Design.
• Communauté plus restreinte que MkDocs ou Docusaurus, documentation officielle moins exhaustive.

4. Considerations de migration¶

Choisir une plateforme documentaire est une decision durable : la migration d'une solution vers une autre implique un effort de conversion des contenus, une periode de transition et un risque de perte de fidelite (mise en forme, liens internes, metadonnees).

Quelques points de vigilance selon le scenario de migration :

• Depuis Confluence vers MkDocs : des outils comme confluence-to-markdown automatisent partiellement la conversion, mais la mise en forme des macros complexes (diagrammes, tableaux de bord) necessite une reprise manuelle. Prevoir une phase de revue page par page sur les contenus critiques.
• Depuis BookStack vers MkDocs : l'export JSON ou HTML de BookStack peut etre converti en Markdown via des scripts, mais la structure Shelves/Books/Chapters doit etre remappee manuellement vers l'arborescence de fichiers MkDocs.
• Depuis Docusaurus vers MkDocs : la migration est la plus simple des quatre scenarios, les deux outils partageant le format Markdown. Les composants MDX spécifiques (JSX inline) doivent etre remplaces par des équivalents MkDocs (admonitions, blocs de code etendus).
• Depuis MkDocs vers Docusaurus : migration directe des fichiers .md, adaptation du fichier de navigation (mkdocs.yml → sidebars.js), et remplacement des plugins Python par leurs équivalents Node.js.

5. Recommandation¶

Au regard des critères evalues, MkDocs Material est la solution la mieux adaptée pour une organisation technique cherchant a intégrer la documentation dans son cycle de développement.

Les arguments determinants sont les suivants :

• Alignement Git-first : les sources Markdown vivent dans le dépôt, l'historique est automatiquement disponible, les revues de documentation suivent le même processus que les revues de code (pull request, CI/CD).
• Zero runtime en production : un site statique est deployable sur un CDN, sans serveur applicatif a maintenir, avec une surface d'attaque minimale.
• Theming et extensibilite : le theme Material est le plus abouti de l'ecosysteme des generateurs de documentation ; les plugins Python couvrent la majorite des besoins courants.
• Coût d'exploitation minimal : hebergement sur GitHub Pages, GitLab Pages, Cloudflare Pages ou tout serveur web basique, sans licence.
• Portabilité du contenu : les fichiers Markdown sont lisibles sans outil spécifique et migrables vers n'importe quelle autre solution avec un effort minimal.

La seule limitation notable — la confidentialite multi-niveaux — est adressable par une stratégie de build multiple (un site par audience) ou un plugin de filtrage, et ne remet pas en cause le choix global sur un projet interne ou un produit open-source.

Docusaurus est une alternative crédible si l'équipe maîtrise React et a besoin de versioning documentaire natif ou de composants interactifs. Confluence peut etre pertinent si l'organisation est déjà abonnee a la suite Atlassian et que la cible editoriale est principalement non-technique. BookStack conviendra a une équipe cherchant un wiki self-hosted simple, sans contrainte de workflow Git.