Commencez par le contenu, pas par la page d’accueil
Une démonstration superbe peut être mauvaise pour votre documentation. Avant de comparer les thèmes, listez ce que le système doit publier : longs manuels, API reference, tutoriels, pages générées, versions, plusieurs langues, milliers d’articles ou un mélange.
Décrivez ensuite qui écrit. Des engineers qui modifient Markdown dans Git chaque jour n’ont pas les mêmes besoins que des experts occasionnels dans un navigateur.
Comparez le modèle de contenu
Sphinx est fort pour les références croisées, directives structurées, longs documents techniques et extensions. MkDocs convient bien à un workflow Markdown-first simple. Astro est un framework web plus large, orienté contenu, avec typed content collections, assets, routing et layouts très flexibles ; cette flexibilité signifie aussi que l’équipe possède davantage le produit éditorial.
Le but n’est pas de couronner un gagnant, mais d’adapter l’abstraction au travail.
Calculez la surface de maintenance
Comptez plugins custom, overrides de thème, étapes de build et conventions privées. Chaque customisation deviendra une tâche lors d’une future mise à jour. Ne demandez pas seulement « pouvons-nous le modifier ? », mais « le prochain maintainer comprendra-t-il pourquoi ? ».
Prototypez les cas difficiles
Construisez un spike avec grande table, reuse, localisation, code, images, redirects, métadonnées de recherche et page longue. Testez un volume représentatif.
N’évaluez pas seulement la home.
Gardez une sortie possible
Séparez autant que possible la sémantique du contenu du markup spécifique au thème. Préférez Markdown ordinaire et composants définis à des centaines de fragments HTML ad hoc. Documentez le schema des métadonnées.
Un générateur est une infrastructure, pas une identité. Choisissez celui qui facilite la publication fiable aujourd’hui et laisse une voie de migration demain.
Exemple pratique
Traitez « Choisir un générateur de documentation sans choisir une religion » comme une petite évaluation et non comme une comparaison de listes de fonctions. Choisissez trois contenus réels : une page simple, une page avec code ou données structurées et une page difficile avec navigation, réutilisation ou localisation. Testez-les et notez ce qui devient plus simple ainsi que le nouveau coût de maintenance.
Évaluez le travail répété de l’équipe :
- la source est-elle compréhensible pour l’auteur ;
- le relecteur voit-il un diff significatif ;
- un échec de build indique-t-il un problème corrigeable ;
- le contenu peut-il être déplacé, localisé ou réutilisé sans nettoyage manuel.
Un bon outil réduit l’incertitude lors de l’écriture, de la revue et de la publication. Si la complexité se déplace simplement vers une configuration fragile, des plugins ou la mémoire d’une seule personne, ce coût fait partie du choix.
Checklist éditorial rapide
- Commencez par le contenu, pas par la page d’accueil. Une démonstration superbe peut être mauvaise pour votre documentation.
- Comparez le modèle de contenu. Sphinx est fort pour les références croisées, directives structurées, longs documents techniques et extensions.
- Calculez la surface de maintenance. Comptez plugins custom, overrides de thème, étapes de build et conventions privées.
- Prototypez les cas difficiles. Construisez un spike avec grande table, reuse, localisation, code, images, redirects, métadonnées de recherche et page longue.
