Commencez par le problème, pas par Git
Docs-as-Code est souvent présenté comme une pile d’outils : Markdown, Git, pull requests, CI et générateur statique. L’équipe discute alors d’éditeurs avant de demander quel problème documentaire elle cherche à résoudre : pages obsolètes, revue lente, terminologie incohérente, liens cassés ou publication dépendante d’une seule personne.
L’approche n’a de valeur que si elle réduit réellement cette friction.
Ce que contient réellement Docs-as-Code
| Étape | Action | Version simple | Version plus mature |
|---|---|---|---|
| Source | modifier le contenu | Markdown/AsciiDoc dans Git | contenu structuré + schéma de métadonnées |
| Édition | travailler sur le texte | éditeur web GitHub | github.dev, VS Code, IDE ou authoring UI |
| Preview | voir la future page | build local/web | preview par changement |
| Contrôles | détecter la routine | liens + build | style, termes, API, accessibilité, locales |
| Revue | vérifier le sens | un reviewer | SME + revue éditoriale |
| Publication | mettre à jour le site | manuel | CI/CD après contrôles |
Il ne faut pas maximiser la complexité de chaque ligne, mais choisir le niveau minimal qui réduit le risque réel.
Un format texte n’impose pas un IDE
GitHub permet de modifier un fichier directement dans le navigateur. github.dev ajoute recherche, coloration et gestion des changements sans clone local. Un SME occasionnel peut donc corriger une information sans apprendre terminal et rebase.
| Participant | Suffit généralement | À ne pas imposer sans raison |
|---|---|---|
| Technical writer | github.dev, VS Code ou éditeur préféré |
IDE précis |
| SME occasionnel | éditeur web + preview | terminal, rebase, build local |
| Développeur | IDE + Git | CMS séparé si Markdown convient |
| Éditeur | navigateur/authoring UI | détails internes du pipeline |
Le format canonique et l’interface d’écriture sont deux décisions différentes.
Un workflow de bout en bout raisonnable
Changement produit → brouillon → preview → contrôles automatiques → revue technique → revue éditoriale → merge → publication → contrôle en production.
Une petite équipe peut combiner plusieurs rôles. Le pull request n’est pas un rituel. Dans une organisation plus grande, le SME confirme les faits et le technical writer porte la tâche utilisateur, la structure, la terminologie et la clarté.
Quels contrôles automatiser
| Contrôle | Détecte | Erreur utile |
|---|---|---|
| Build | syntaxe, includes, templates | fichier + cause |
| Liens internes | pages/anchors supprimés | source + destination |
| Métadonnées | title, owner, locale, revision | champ invalide |
| Structure | headings incorrects | heading concerné |
| Terminologie | termes obsolètes | terme + remplacement |
| Style lint | règles éditoriales | explication courte |
| Exemples de code | syntaxe/format | exemple + erreur |
| Contrat API | dérive du schema/OpenAPI | champ/endpoint |
| Images | asset, alt, taille | fichier + violation |
| Locales | langue/révision manquante | article + langue |
| Secrets | token/clé | type de détection sans exposer le secret |
Un warning que personne ne corrige doit être amélioré ou supprimé. Le bruit apprend à ignorer le pipeline.
Combien de temps peut-on économiser ?
Il n’existe pas de pourcentage universel honnête. Utilisons des hypothèses visibles : 40 changements par mois × 20 minutes de vérifications manuelles = 13 h 20 min de routine active. Après automatisation, 2 minutes par changement pour lire les résultats donnent environ 1 h 20 min.
Hypothèse : 40 × 20 minutes contre 40 × 2 minutes. Modèle de planification, pas benchmark sectoriel.
La recherche sur la revue industrielle montre que l’automatisation du travail répétitif peut avoir un impact mesurable, sans permettre de copier directement un pourcentage vers la documentation.
Mesurez votre effet au lieu d’inventer une étude
TechWriters ne doit pas prétendre avoir étudié plusieurs projets avant de l’avoir fait. Pendant quatre semaines, mesurez temps actif de l’auteur, attente de revue, temps SME/éditeur, défauts après publication, délai jusqu’à production et faux positifs. Automatisez ensuite une classe de problèmes — liens, métadonnées et build — puis recommencez.
On obtient ainsi une vraie étude de cas avec son contexte.
Humains et machines doivent vérifier des choses différentes
| Machine | Humain |
|---|---|
| le lien existe | il mène au bon endroit |
| le heading existe | la structure suit la tâche |
| le terme est autorisé | il est compréhensible |
| l’exemple correspond au schema | il enseigne un cas réel |
| la page build | elle aide le lecteur à réussir |
Les contrôles LLM peuvent signaler des contradictions, mais les faits doivent être confirmés par produit, spécification, test ou expert responsable.
Où commence le fanatisme
Il commence quand la pureté du processus compte plus que les personnes. Si un SME peut corriger un nom de paramètre dans le navigateur en deux minutes, ne lui imposez pas Node.js, clone local et rebase. Gardez une porte d’entrée simple : édition web, issue, assisted authoring ou une personne qui porte le changement dans Git.
Déployer Docs-as-Code par étapes
- Semaine 1 : sources dans Git et historique clair.
- Semaine 2 : preview et build automatique.
- Semaine 3 : trois à cinq contrôles utiles.
- Semaine 4 : séparer revue technique et éditoriale si nécessaire.
- Après un mois : mesurer lead time, routine, erreurs et bruit des warnings.
Docs-as-Code fonctionne quand modifier, vérifier et publier devient plus simple.
