La documentation qui n'est pas maintenue est pire que pas de documentation. L'approche docs-as-code aligne la documentation sur les mêmes workflows que le code, pour qu'elle reste vivante.
La documentation technique souffre d'un problème universel : elle vieillit mal. Écrite une fois lors de la conception, elle n'est plus mise à jour lors des évolutions. Deux ans plus tard, elle décrit un système qui n'existe plus. Le problème n'est pas le manque de motivation — c'est le coût de mise à jour, découplé du code lui-même. La solution : traiter la documentation comme du code.
L'approche docs-as-code stocke la documentation dans le même repository que le code, en Markdown ou AsciiDoc. Les mises à jour de doc font partie de la même PR que les modifications de code — pas de PR acceptée sans doc mise à jour si le comportement change. Des outils comme MkDocs, Docusaurus ou VitePress génèrent un site statique propre à partir des fichiers Markdown. La doc est versionnée, reviewée, testable.
Les docs vivantes vont plus loin : elles sont générées depuis le code lui-même. Les spécifications OpenAPI générées par springdoc, les diagrammes de classes générés par PlantUML depuis des annotations, les exemples de code extraits directement des tests — tout ce qui peut être généré automatiquement évite la désynchronisation. Notion reste utile pour la documentation produit et les processus d'équipe, mais pour la documentation technique, la proximité avec le code est imbattable. La règle d'or : si la documentation peut se désynchroniser du code, elle le sera.
- Stockez la doc technique dans le repo, en Markdown
- Exigez les mises à jour de doc dans les PR fonctionnelles
- Générez ce qui peut l'être (OpenAPI, diagrammes)
- Réservez Notion aux docs produit et organisationnelles