Garder sa documentation à jour quand on livre chaque semaine
Un client vous écrit : « Votre guide dit d’aller dans Paramètres, puis Calendrier. Il n’y a pas de Calendrier. » Il a raison. Vous l’avez déplacé dans Comptes il y a six semaines. La pull request a été relue, testée et livrée. L’article d’aide n’a pas changé, parce que personne n’avait pour mission de le modifier.
C’est ainsi que naît presque toute documentation obsolète. Pas par paresse, mais par l’absence de lien entre « nous avons modifié le produit » et « ces articles décrivent la partie que nous avons modifiée ».
Pour garder votre documentation à jour quand vous livrez chaque semaine, intégrez la doc à la pull request : chaque pull request répond à « cela change-t-il ce que voit un client ? », nomme les articles d’aide concernés et livre la modification de la doc dans la même pull request ou dans une pull request liée. Automatisez ensuite les parties mécaniques (captures d’écran, entrées de changelog) et surveillez les tickets de support et les recherches dans le centre d’aide pour repérer la dérive qui passe entre les mailles.
Le reste de cet article explique comment mettre cela en place sans embaucher de rédacteur technique.
Pourquoi la documentation devient obsolète
La dérive de la documentation a quelques causes prévisibles, et aucune ne se règle avec « soyons plus attentifs ».
La doc vit ailleurs. Le code est sur GitHub. La doc est dans Intercom, Zendesk, Notion ou un espace GitBook. Rien ne relie un fichier de l’un à une page de l’autre, si bien qu’une modification de l’un n’incite jamais à regarder l’autre.
Celui qui sait n’est pas celui qui écrit. L’ingénieur qui a déplacé les paramètres du calendrier sait exactement ce qui a changé. Celui qui entretient le centre d’aide l’apprend par un client.
La doc est corrigée par lots. « Nous ferons une passe sur la doc à la fin du trimestre. » Pendant ce temps, chaque livraison hebdomadaire grignote l’exactitude, et la grande réécriture prend tellement de temps qu’elle est déjà en partie périmée quand elle sort.
Personne ne sait quels articles sont concernés. Même une équipe motivée ne peut pas vérifier 80 articles après chaque livraison. Alors elle n’en vérifie aucun.
Le schéma est le même que pour tout autre travail d’entretien. De petites mises à jour continues valent mieux que des exploits périodiques.
Faire de la doc un critère d’achèvement
Le changement le plus efficace : ajouter une section documentation à votre modèle de pull request. GitHub la préremplira dans chaque pull request si vous placez un fichier dans .github/pull_request_template.md (le guide de GitHub sur les modèles de pull request).
## Docs impact
- [ ] This changes something a customer can see or do
- Help articles affected: <!-- slugs or links, or "none" -->
- [ ] Screenshots need re-capturing
- [ ] Changelog entry drafted (or marked "internal only")
Cela ressemble à de la bureaucratie pendant environ deux semaines. Puis cela devient le moment où un ingénieur se dit « ah, l’article d’accueil mentionne cet écran » alors que le contexte est encore frais. Une correction de deux lignes rédigée par la personne qui a fait la modification vaut mieux qu’une correction parfaite rédigée un mois plus tard au jugé.
Deux règles pour que cela tienne :
- Les relecteurs vérifient la case. Si une pull request modifie manifestement l’interface et dit « aucun impact sur la doc », le relecteur demande pourquoi. Comme pour un test manquant.
- La modification de la doc peut être brute. Les ingénieurs n’ont pas besoin de rédiger une prose léchée. « Étape 6 désormais : ouvrir Comptes, puis Paramètres de disponibilité » suffit. Quelqu’un pourra peaufiner la formulation plus tard. L’exactitude d’abord.
Associer les articles d’aide au code qu’ils décrivent
La liste de contrôle des pull requests suppose que les gens se souviennent des articles qui existent. Aidez-les avec une simple correspondance entre chemins de code et articles :
# docs-map.yml
- paths: ["src/features/calendar/**", "src/pages/accounts/availability*"]
articles: ["connect-your-calendar", "set-your-availability"]
- paths: ["src/features/billing/**"]
articles: ["change-your-plan", "update-payment-method", "download-invoices"]
- paths: ["src/features/onboarding/**"]
articles: ["get-started"]
Une petite étape d’intégration continue lit alors la liste des fichiers modifiés (git diff --name-only origin/main...HEAD), les compare aux motifs et poste un commentaire sur la pull request : « Cette pull request touche le code du calendrier. À vérifier : connect-your-calendar, set-your-availability. » C’est une quarantaine de lignes de script, et cela transforme « pensez à la doc » en une liste précise sur laquelle on peut cliquer.
Cette correspondance devient obsolète aussi, bien sûr. Gardez-la près du code et ajoutez une ligne chaque fois que quelqu’un rédige un nouvel article. Elle reste bien plus facile à entretenir que la documentation elle-même.
Si votre documentation vit dans le même dépôt (docs-as-code avec Docusaurus, Mintlify ou la synchronisation Git de GitBook, par exemple), vous pouvez aller plus loin : une entrée CODEOWNERS sur le dossier de la doc garantit que quelqu’un qui s’en soucie relit chaque modification.
Écrire une documentation qui vieillit plus lentement
Certains choix d’écriture facilitent beaucoup l’entretien de la documentation :
- Décrivez des tâches, pas des mises en page. « Ouvrez Comptes et choisissez Paramètres de disponibilité » survit à une refonte. « Cliquez sur le bouton violet en haut à droite » non.
- Utilisez les intitulés exacts de l’interface, en gras. Quand un intitulé change, une recherche de l’ancien intitulé retrouve tous les articles à corriger.
- Ne répétez pas les faits volatils. Limites d’offre, prix et durées d’essai changent. Placez-les sur une seule page et faites un lien plutôt que de les redire dans dix articles.
- Capturez la partie stable. Recadrez sur l’élément dont parle l’étape plutôt que sur tout l’écran, pour qu’une modification de la barre latérale n’invalide pas chaque image.
- Affichez la date de « dernière mise à jour ». Elle vous garde honnête et indique aux lecteurs quelle confiance accorder à la page.
Plus de détails sur la structure dans notre guide pour rédiger des articles de centre d’aide que les gens utilisent vraiment.
Automatiser les parties mécaniques
Une partie de l’entretien de la documentation relève du jugement. Beaucoup n’est que corvées qu’un script fait mieux.
Les captures d’écran. Refaire les images à la main est la première chose à automatiser. Un script Playwright sur un compte de démonstration pré-rempli, lancé en intégration continue, vous donne des images fraîches et cohérentes à chaque fusion. Nous détaillons le script complet dans comment créer automatiquement des captures d’écran de votre produit.
Les entrées de changelog. Vos pull requests fusionnées décrivent déjà ce qui a été livré. Les transformer en changelog destiné aux clients consiste surtout à réécrire du jargon d’ingénieur en langage simple et à regrouper par Added, Changed et Fixed, la convention popularisée par Keep a Changelog. Voir comment rédiger un changelog que vos clients lisent pour des modèles.
Les vidéos. Si vous avez des vidéos de présentation, la même correspondance entre chemins de code et articles vous indique lesquelles doivent être réenregistrées. Enregistrer l’image et la voix séparément rend la refonte rapide ; voici le processus pour les vidéos de présentation de produit.
Repérer la dérive que vous avez déjà
Même avec un bon processus, certaines modifications passent entre les mailles. Ces signaux vous disent où :
- Les tickets de support qui citent votre documentation. « Le guide dit X mais je vois Y » est un rapport de bug gratuit. Étiquetez-les et corrigez l’article le jour même.
- Les recherches sans résultat dans le centre d’aide. Des gens qui cherchent le nom d’une fonctionnalité que vous avez renommée, ou une fonctionnalité que vous n’avez jamais documentée.
- Les retours sur les articles. Si votre centre d’aide propose « Cet article vous a-t-il été utile ? », lisez chaque semaine les commentaires négatifs. Ils sont généralement précis.
- Un court balayage de vos pages les plus vues. Une fois par mois, parcourez vos 20 articles les plus consultés dans le vrai produit. Cela prend environ une heure et couvre l’essentiel de ce que lisent vraiment les clients.
Ne documentez pas ce qui n’est pas livré
Un piège pour les équipes qui vont vite : une pull request est fusionnée derrière un drapeau de fonctionnalité, quelqu’un met consciencieusement la doc à jour, et maintenant le centre d’aide décrit une fonctionnalité que la plupart des clients ne voient pas. Les clients sont perdus et le support reçoit les tickets.
Retenez les modifications de la doc pour le travail protégé par un drapeau tant que le drapeau n’est pas activé pour tout le monde (ou rédigez-les en brouillon et publiez-les avec le déploiement). Même chose pour les entrées de changelog.
Les outils qui aident à entretenir la documentation
Les helpdesks comme Intercom, Zendesk et Help Scout ont des éditeurs de centre d’aide tout à fait corrects, mais ils ne savent rien de ce qu’il y a dans votre code, si bien que tout le travail de liaison décrit plus haut vous revient. Les plateformes docs-as-code comme GitBook et Mintlify gardent la doc dans Git, ce qui apporte la relecture par pull request et l’historique, et fonctionnent mieux quand vos rédacteurs sont à l’aise dans un dépôt. Les nouveaux outils de centre d’aide conçus autour de l’IA, dont Ferndesk, essaient de combler le fossé sous d’autres angles.
Nous avons conçu Ellie Docs précisément autour du lien avec la pull request. Vous connectez un dépôt GitHub, et Ellie cartographie vos fonctionnalités et relie chaque article d’aide aux fonctionnalités qu’il décrit. À chaque pull request fusionnée, il vérifie quels articles sont concernés par la modification et propose des corrections sous forme de diff relisible, avec une courte explication. Vous acceptez ou rejetez chacune. Rien ne se publie tout seul.

Il rédige aussi des entrées de changelog à partir des mêmes pull requests fusionnées, et retient tout ce qui est encore derrière un drapeau jusqu’à sa mise en ligne.

Vous pouvez faire tout ce qui est décrit dans cet article à la main, et beaucoup d’équipes le font. Ellie se charge simplement de la partie « quels articles cette pull request touche-t-elle, et que faut-il changer ? », à chaque fois.
Questions fréquentes
Qui doit être responsable de la documentation dans une petite équipe ? Une personne nommée est responsable du centre d’aide dans son ensemble (souvent le fondateur ou celui qui gère le support), mais chaque ingénieur est responsable de l’impact sur la doc de ses propres pull requests. Une responsabilité partagée sans responsable nommé veut dire qu’il n’y en a pas.
À quelle fréquence relire notre documentation ? En continu pour les changements (via la liste de contrôle des pull requests), plus un parcours mensuel de vos articles les plus consultés. De grandes réécritures trimestrielles montrent que la partie continue ne se fait pas.
Le docs-as-code vaut-il le coup pour la documentation d’aide aux clients ? Si ceux qui écrivent sont des ingénieurs, oui. Si le support ou le marketing en écrit l’essentiel, un éditeur de centre d’aide classique avec la liste de contrôle des pull requests et une correspondance de la doc fonctionne généralement mieux que de forcer tout le monde à passer par Git.
Quel est le gain le plus rapide si notre documentation est déjà très obsolète ? Corrigez les 10 articles les plus consultés, ajoutez le modèle de pull request et commencez à étiqueter les tickets de support qui mentionnent la doc. Cela arrête l’hémorragie avant de vous attaquer à la longue traîne.
Si vous préférez que les mises à jour de la doc vous soient proposées à chaque pull request, essayez Ellie Docs gratuitement. Connectez un dépôt, obtenez un centre d’aide rédigé et relisez les modifications suggérées au fil de vos livraisons.