Passer au contenu principal
La documentation s’éloigne du produit dès qu’elle est publiée. Les fonctionnalités changent, les APIs évoluent et les éléments d’interface sont renommés. Sans maintenance délibérée, la documentation devient silencieusement un handicap : les utilisateurs suivent des étapes obsolètes, rencontrent des erreurs et perdent confiance en votre produit. Ce guide explique comment intégrer la maintenance dans votre flux de travail afin que la documentation reste précise sans nécessiter des efforts constants de toute l’équipe.

​
Attribuez la responsabilité

La documentation sans responsable n’est pas maintenue. Quelqu’un doit se sentir responsable de chaque section de votre documentation pour que les problèmes soient réellement résolus. La responsabilité ne signifie pas qu’une seule personne écrit tout. Cela signifie que quelqu’un est redevable de l’exactitude. Modèles de responsabilité courants :
  • Centralisé : Une équipe de documentation ou un rédacteur technique est responsable de tout le contenu. Fonctionne bien pour les petites équipes et les produits où l’équipe de documentation a suffisamment de contexte pour tout maintenir.
  • Distribué : Les responsables produit, ingénierie ou d’équipe sont responsables de la documentation de leurs domaines. Fonctionne bien pour les produits plus importants avec des domaines spécialisés. Nécessite un coordinateur pour assurer la cohérence et détecter les lacunes.
  • Hybride : Une équipe de documentation est responsable du contenu principal (prise en main, navigation, style), tandis que les équipes de domaine sont responsables de la référence technique et des guides de leurs fonctionnalités.
Quel que soit le modèle que vous utilisez, rendez la responsabilité visible — dans les fichiers eux-mêmes, dans un tableur partagé ou dans votre outil de gestion de projet.

​
Établissez une cadence de révision

Les révisions régulières détectent les problèmes avant les utilisateurs. La bonne cadence dépend de la rapidité avec laquelle votre produit évolue.

​
Révisions basées sur des déclencheurs

L’approche la plus fiable consiste à réviser la documentation chaque fois que le produit change :
  • Mettez à jour la documentation dans le même pull request que la modification du code
  • Incluez une vérification de la documentation dans votre checklist de lancement de fonctionnalité
  • Exigez une validation de la documentation avant de fermer tout ticket qui modifie le comportement visible par l’utilisateur
C’est plus durable que les révisions planifiées car la mise à jour de la documentation se fait pendant que le changement est encore frais dans l’esprit de l’ingénieur ou du PM.

​
Révisions planifiées

Pour le contenu non lié à une fonctionnalité spécifique, les révisions planifiées détectent la dérive accumulée :
  • Mensuel : Révisez les pages à fort trafic pour vérifier leur exactitude. Ces pages affectent le plus d’utilisateurs, elles méritent donc une attention plus fréquente.
  • Trimestriel : Auditez les pages signalées avec des scores de retour bas ou une forte corrélation avec les tickets de support.
  • Annuel : Audit complet du contenu — recherchez des exemples obsolètes, des approches dépassées et du contenu qui ne reflète plus le produit.

​
Utilisez l’automatisation pour détecter le contenu obsolète

Suivre manuellement les dates de révision sur des centaines de pages n’est pas scalable. Automatisez ce que vous pouvez :
  • Signalez les pages qui n’ont pas été mises à jour depuis plus de 90 jours pour une révision
  • Surveillez les analyses de recherche pour les requêtes qui ne renvoient aucun résultat — celles-ci signalent souvent du contenu qui devrait exister mais n’existe pas
  • Utilisez les vérifications CI pour appliquer les exigences de frontmatter et détecter les liens cassés à chaque pull request
Utilisez les workflows pour exécuter des vérifications de maintenance automatisées selon un calendrier — signalant le contenu obsolète, vérifiant les métadonnées manquantes ou détectant les pages avec des scores de retour constamment bas.

​
Automatisez ce que vous pouvez

L’automatisation ne peut pas remplacer le jugement éditorial, mais elle réduit le travail manuel nécessaire pour détecter les problèmes courants.
  • Liens cassés : Exécutez mint broken-links avant de publier pour détecter les liens internes et externes cassés avant que les utilisateurs ne les rencontrent.
  • Application du style : Un linter comme Vale vérifie la prose selon des règles configurables — cohérence terminologique, voix passive, ponctuation manquante — à chaque pull request. Consultez Style et ton pour en savoir plus sur le linting.
  • Mises à jour de la référence API : Si votre référence API est générée à partir d’une spécification OpenAPI, automatisez la génération de la spécification dans votre pipeline de publication afin que la référence ne prenne jamais de retard.
  • Brouillons de documentation automatisés : Utilisez l’API de l’agent pour générer automatiquement des brouillons de documentation lorsque du code est fusionné.

​
Savoir quand réécrire

Les corrections incrémentales ne fonctionnent pas toujours. Quand une page a accumulé trop de mises en garde, de contournements et de contradictions, la modifier devient plus difficile que de repartir de zéro. Signes qu’une page nécessite une réécriture plutôt que des modifications :
  • Les utilisateurs signalent régulièrement de la confusion malgré plusieurs séries de modifications
  • La page s’est étendue pour couvrir plusieurs sujets distincts qui devraient être des pages séparées
  • Le produit a changé si fondamentalement que la structure de la page ne correspond plus au fonctionnement de la fonctionnalité
  • Plus de la moitié du contenu concerne des cas particuliers, des mises en garde ou “ceci ne s’applique pas si…”
Une réécriture est moins intimidante lorsque vous commencez par un audit structuré : documentez ce qui manque, ce qui est trompeur et ce qui est redondant avant d’écrire quoi que ce soit. Réalisez les réécritures en sprints ciblés plutôt que d’essayer de tout faire en une fois.

​
Supprimez ce qui n’a plus sa place

Une documentation erronée est pire que pas de documentation du tout. Les utilisateurs qui suivent des étapes inexactes perdent du temps et de la confiance en votre produit et votre équipe. Quand le contenu est complètement inexact et ne peut pas être corrigé immédiatement, supprimez-le plutôt que de le laisser en ligne. Lors de la suppression de contenu :
  • Configurez une redirection de l’ancienne URL vers la page actuelle la plus pertinente
  • Vérifiez les liens internes pointant vers la page supprimée et mettez-les à jour
  • Envisagez si une brève note dans le journal des modifications est appropriée si la page était largement utilisée

​
Questions fréquemment posées

Faites-en une étape obligatoire, pas une demande. Incluez la documentation dans votre définition de terminé pour les fonctionnalités. Placez les mises à jour de documentation dans le même pull request que les modifications de code — cela garde le contexte frais et facilite la révision conjointe. Quand les ingénieurs comprennent que la documentation obsolète génère des tickets de support qui leur reviennent, l’incitation à la maintenir devient plus claire.
Gardez la documentation dépréciée accessible mais clairement marquée. Ajoutez un avis en haut de la page indiquant que la fonctionnalité est dépréciée, quand elle sera supprimée et vers quoi les utilisateurs doivent migrer. Ne supprimez pas la page tant que la fonctionnalité n’est pas réellement supprimée — les utilisateurs sur des versions antérieures en ont encore besoin. Une fois supprimée, redirigez l’URL vers le guide de migration ou la documentation de la fonctionnalité de remplacement.
Deux pratiques couvrent l’essentiel de la valeur : mettre à jour la documentation dans le même PR que les modifications de code et exécuter mint broken-links avant chaque publication. Ces deux habitudes préviennent les catégories les plus courantes de dérive — instructions obsolètes et liens cassés — sans nécessiter d’infrastructure de documentation dédiée. Ajoutez des révisions planifiées et de l’automatisation à mesure que l’équipe et le produit grandissent.
Par impact. Une page obsolète avec 5 000 visites mensuelles et des scores de satisfaction bas est plus urgente qu’une page périmée que personne ne lit. Utilisez les analyses pour classer le contenu par trafic, croisez avec les scores de retour et corrélez avec le volume de tickets de support pour construire une liste priorisée. Corrigez les pages que les utilisateurs consultent réellement, pas celles qui semblent désordonnées pour l’équipe.