La philosophie 'Docs as Code'
La méthode Docs-as-Code : une philosophie pour une meilleure documentation
Pendant des années, la documentation n’arrivait qu’après le développement. La méthode consistait à collecter des informations — parfois directement auprès des développeurs, mais le plus souvent dans notre propre bulle, entre rédacteurs techniques. Puis un jour, j’ai réalisé quelque chose : j’utilisais Git, j’écrivais en Markdown, je poussais des commits, j’éditais dans VS Code. Attends une minute — je faisais du docs-as-code.
🌤️ Comment j’ai découvert ma devise sur la documentation et le code
Lorsque j’ai créé mon précédent site Coffee Cup début 2019, j’ai rédigé une page intitulée "Rédaction technique" qui commençait par cette phrase : "La rédaction technique est la jumelle du développement."
Ailleurs sur la page, j’expliquais mon idée plus en détail :
"L’époque où la documentation était rédigée à part du développement, dans des services séparés, avec des outils de traitement de texte, est révolue ou tend à l’être. (...) La documentation est la jumelle du développement, une jumelle qui aide et soutient."
À l’époque, je dois avouer que je ne connaissais pas le concept de “Docs-as-Code” — ni même sa philosophie. Ce que j’appelais une “jumelle” était ma propre version du concept, façonnée par l’expérience et l’intuition. Et pourtant, cela m’a conduite à une mise en œuvre très concrète :
Utiliser les mêmes outils et étapes pour produire la documentation que pour produire le code.
La documentation devient une partie intégrante du workflow de développement, et le rédacteur technique est un membre de l’équipe.
🪢 Pourquoi ce binôme fonctionne
Voici quelques avantages que j’ai constatés en travaillant de cette manière :
- La phase de documentation n’est pas repoussée aux dernières minutes avant la livraison.
- Le rédacteur technique n’est plus perçu comme un expert Word avec des compétences en interview (développeur, chef de produit).
- Il utilise les mêmes outils que les développeurs – ce qui facilite et accélère la collaboration.
- Les développeurs rédigent souvent le premier jet ; le rédacteur technique réécrit, enrichit, polit – en se concentrant sur l’expertise de contenu.
- La documentation est à jour et facile à maintenir grâce aux systèmes de contrôle de version comme Git, qui devient un véritable système de gestion documentaire.
Cette approche favorise une vraie coopération. Et dans cet esprit, Markdown est la syntaxe idéale : un langage partagé par toute l’équipe, qui garde la structure sans se soucier du style visuel.
✍️ Le rôle durable du rédacteur
Bien sûr, peu importe à quel point les outils ou les workflows sont collaboratifs, le rédacteur technique joue toujours un rôle essentiel.
Nous garantissons la qualité du contenu, appliquons des standards rédactionnels, ajoutons des schémas et visuels pertinents, définissons la structure de navigation, plaçons les liens stratégiquement, choisissons les bonnes admonitions — et bien plus encore. C’est notre métier.
🪴 Merci à toutes celles et ceux qui ont développé ce concept et contribué à son évolution. En tant que rédactrice technique, je suis reconnaissante.