Une bonne documentation se versionne, se publie automatiquement et reste proche du code. Les générateurs de sites statiques open source rendent cela simple.
Documenter, c'est transmettre durablement. On apprend aux apprenants à écrire en Markdown et à publier un site de doc maintenable.
Points clés
- MkDocs (Material) — Génère un beau site de documentation à partir de fichiers Markdown ; le thème Material est un standard.
- Docusaurus — Générateur React (par Meta) idéal pour la doc de produit avec versionnage et i18n.
- Sphinx — La référence dans l'écosystème Python, avec génération depuis le code (docstrings).
- Antora — Pensé pour la doc multi-dépôts à grande échelle, en AsciiDoc.
Les outils à connaître
Voici une sélection d'outils open source de référence, à mettre entre les mains des apprenants. Tous sont gratuits et reproductibles en autonomie.
- MkDocs (Material) — Génère un beau site de documentation à partir de fichiers Markdown ; le thème Material est un standard.
- Docusaurus — Générateur React (par Meta) idéal pour la doc de produit avec versionnage et i18n.
- Sphinx — La référence dans l'écosystème Python, avec génération depuis le code (docstrings).
- Antora — Pensé pour la doc multi-dépôts à grande échelle, en AsciiDoc.
- HedgeDoc — Édition collaborative de notes Markdown en temps réel, auto-hébergeable.
En pratique
Scénario. Faites créer un dépôt Git avec quelques pages Markdown, configurez MkDocs Material, et publiez automatiquement via un pipeline CI à chaque commit. Les apprenants repartent avec un site de documentation versionné et réutilisable.
Questions fréquentes
Markdown ou un éditeur classique ?
Markdown : léger, versionnable dans Git, et converti en site soigné. C'est la base de la doc moderne « docs-as-code ».
Comment héberger gratuitement ?
Sur des pages statiques (GitLab/GitHub Pages) générées par le pipeline CI, sans serveur à maintenir.
Pour aller plus loin
Pour approfondir : Outils d analyse reseau · Outils d observabilite moderne. Et l'annuaire d'outils pour les fiches détaillées, outil par outil.
Besoin d'un formateur expert ou envie de transmettre ?
tonformateur connecte les écoles et organismes de formation avec des intervenants experts du terrain.
Voir les cours à pourvoir Explorer l'annuaire d'outils →