La documentation a un cycle de vie. Il est créé pour répondre à un besoin, maintenu pour rester précis au fur et à mesure que les choses évoluent, puis finalement retiré lorsque ce besoin n’existe plus. Traiter la documentation comme quelque chose qui s’écrit une fois puis laisse tranquille est la voie la plus fiable vers une base de connaissances à laquelle les lecteurs — et de plus en plus, les systèmes d’IA qui répondent en leur nom — cessent de faire confiance.
Cet article décrit chaque phase du cycle de vie de la documentation ainsi que les pratiques qui maintiennent une base de connaissances saine au fil du temps.
Phase 1 : Créer
La création ne commence pas lorsque vous ouvrez un document vierge, mais lorsque vous identifiez un besoin. Un besoin documentaire existe lorsque les lecteurs ne peuvent pas atteindre un objectif sans aide — et cette aide n’existe pas encore dans votre base de connaissances.
Identifiez ce qui doit être écrit
Les signaux les plus fiables pour les lacunes dans la documentation sont les demandes de support, les retours des utilisateurs et les requêtes de recherche qui ne donnent aucun résultat. Si votre équipe de support répond à la même question dix fois par semaine, cette question nécessite un article. Si les lecteurs recherchent un terme qui n’apparaît pas dans votre base de connaissances, ce terme doit être là.
Considérez votre file d’attente de support comme un retard de documentation. Chaque question qui aurait dû être répondue par des documents — mais qui ne l’était pas — est un écart à combler.
Écrire avec un périmètre défini
Avant d’écrire, définissez exactement ce que l’article abordera ou ne couvrira pas. Un champ d’action défini empêche les articles de s’étendre indéfiniment et les maintient concentrés sur un objectif unique pour les lecteurs. Notez le périmètre en une phrase avant de commencer : « Cet article explique comment [tâcher] pour [le public], en partant de [état préalable]. »
Si vous ne pouvez pas écrire cette phrase clairement, vous n’avez pas encore assez de clarté sur ce que vous écrivez. Clarifiez d’abord le champ d’application.
Critique avant publication
Chaque article doit être examiné par au moins une autre personne avant sa publication — idéalement quelqu’un ayant une expertise dans le domaine capable de vérifier l’exactitude, et quelqu’un qui ne connaît pas le sujet et qui peut vérifier sa clarté. Ces deux critiques détectent différents types de problèmes. Une personne à la fois experte et peu familière avec le point de vue du lecteur ne remplace pas les deux.
Phase 2 : Entretien
La maintenance est la phase que la plupart des bases de connaissances négligent et souffrent le plus de leur négligence. Une base de connaissances non maintenue ne reste pas neutre — elle se dégrade activement. Les articles inexacts sont lus et réagis. Les étapes obsolètes orientent les lecteurs dans la mauvaise direction. Des termes qui ne signifient plus ce qu’ils signifiaient autrefois créent de la confusion.
Ce risque ne se limite plus aux lecteurs humains. Un assistant IA citant un article obsolète peut révéler des informations obsolètes ou erronées à quelqu’un qui n’aurait jamais trouvé cet article par recherche ou navigation — souvent présenté avec la même assurance que le contenu exact. Une base de connaissances non tenue ne perd pas simplement discrètement la confiance des lecteurs qui tombent sur d’anciens articles ; Il peut activement propager des erreurs dans tous les systèmes qui les récupère et les résume.
Construis un planning de révision basé sur deux variables, pas sur une seule
Fixez une date de relecture à chaque article. L’intervalle approprié dépend de deux choses qui travaillent ensemble, pas seulement d’une seule :
- À quelle fréquence le contenu sous-jacent change. Les articles sur les fonctionnalités en évolution rapide peuvent nécessiter une revue trimestrielle ; Les articles conceptuels fondamentaux peuvent nécessiter une revue annuelle.
- Type de contenu. Un article de référence (comme une API ou une liste de paramètres) a tendance à devenir obsolète dès qu’un système sous-jacent change et doit être examiné au même rythme que le cycle de publication de ce système. Un article conceptuel expliquant un modèle mental stable peut s’étendre plus longtemps entre les évaluations. Un article de dépannage doit être consulté chaque fois que le symptôme décrit change de forme — même si la caractéristique sous-jacente n’a pas changé sur le papier.
Définissez des rappels de révision dans votre système de flux de travail. Lorsqu’une date de relecture arrive, le propriétaire de l’article vérifie si le contenu est toujours exact et le met à jour sinon. Si c’est exact, ils réinitialisent la date d’évaluation et passent à autre chose. Cela prend quelques minutes pour un article qui n’a pas changé et des heures seulement lorsque des mises à jour importantes sont nécessaires.
Associez la documentation aux modifications des produits
La manière la plus fiable de s’assurer que la documentation reste à jour est d’intégrer les mises à jour dans le processus de publication du produit, et non une réflexion après coup. Lorsqu’une fonctionnalité change, la documentation de cette fonctionnalité évolue en même temps — pas quelques semaines plus tard, lorsque quelqu’un remarque la différence.
Cela nécessite une relation entre l’équipe de documentation et la personne qui gère les sorties de produits. Le processus n’a pas besoin d’être complexe : un élément de checklist partagé indiquant « documentation mise à jour » avant la publication suffit aussi.
Répondre aux retours
Les retours des lecteurs — que ce soit via des notes, des commentaires ou des tickets de support — sont le signal le plus direct qu’un article a besoin d’attention. Un article qui reçoit constamment de mauvaises notes ou suscite des questions de soutien complémentaires vous dit quelque chose. Enquêtez.
Observez aussi les signaux au-delà du retour direct : une augmentation du taux de recherches qui tombent sur un article mais sont immédiatement suivies d’une recherche répétée (suggérant que l’article n’a pas répondu à la question), ou un changement notable dans la fréquence à laquelle un assistant IA ou un moteur de recherche cite l’article, peuvent tous deux indiquer un problème de qualité avant qu’un seul lecteur ne se plaigne.
N’attendez pas que les retours s’accumulent. Un seul commentaire d’un lecteur disant « l’étape 4 ne fonctionne pas » suffit à déclencher un avis.
Montrer aux lecteurs que l’article est maintenu
Une date visible de « dernière mise à jour », et — pour des changements significatifs — une brève note sur ce qui a changé, renforcent la confiance des lecteurs d’une manière qu’un article invisible ne peut pas faire. Les lecteurs (et les critiques) sont plus enclins à faire confiance à un article qui montre clairement des signes d’entretien qu’à un article qui ne donne aucun signe dans un sens ou dans l’autre.
Phase 3 : Retraite (ou consolidation)
La retraite documentaire est la partie la moins pratiquée du cycle de vie, mais elle compte autant que la création et la maintenance. Un article sur une fonctionnalité obsolète, un processus qui n’existe plus, ou une version de produit qui n’est plus prise en charge n’est pas neutre — il est trompeur. Les lecteurs qui le découvrent et le suivent rencontreront des problèmes ou des erreurs et perdront confiance dans votre documentation dans son ensemble. Pire encore, un système d’IA sans savoir que l’article est obsolète peut le citer comme un fait actuel indéfiniment.
Identifier les candidats à la retraite
Un article est un candidat à la retraite lorsque :
- La caractéristique ou le processus décrit n’existe plus.
- Il a été supplanté par un article plus récent qui traite le même sujet de manière plus précise.
- La version produit à laquelle il s’applique n’est plus prise en charge.
- Il reçoit régulièrement de faibles notes et le sujet sous-jacent ne s’applique plus.
- Les analyses montrent qu’il reçoit presque aucun trafic et que le sujet n’est pas nécessaire pour les lecteurs.
Sachez quand consolider au lieu de prendre votre retraite
Tous les essais de problèmes ne doivent pas être retirés complètement. Un scénario courant est deux articles qui ont dérivé vers le même sujet — souvent écrits par des personnes différentes à différents moments — sans qu’aucun des deux ne soit erroné. Lorsque cela se produit, la bonne décision est généralement de les regrouper en un seul article faisant autorité plutôt que de supprimer l’un et de conserver l’autre, car l’article survivant peut lui-même être incomplet. Fusionner le contenu exact des deux, retirer le perdant avec une redirection vers le résultat fusionné, et noter la consolidation dans l’historique des mises à jour de l’article survivant.
Prends ta retraite avec grâce
Retirer un article ne signifie pas toujours le supprimer immédiatement. Si l’article peut encore être pertinent pour les lecteurs sur les anciennes versions, archivez-le avec un avis clair en haut expliquant que le contenu ne s’applique qu’à une version spécifique et en reliant à la documentation actuelle.
Si l’article est réellement obsolète, supprimez-le — et configurez une redirection de son URL vers l’article actuel le plus pertinent. Un lecteur qui a mis en favori un article retiré devrait trouver un endroit utile, et non sur une erreur 404. Une redirection empêche également un moteur de recherche ou un système d’IA de continuer à faire apparaître un lien mort bien après la disparition de l’article.
Propriété et responsabilité
Un cycle de vie de documentation ne fonctionne que si quelqu’un en est responsable. Chaque article devrait avoir un propriétaire — une personne responsable de son exactitude et de sa valeur. Dans une petite équipe, une seule personne peut tout posséder. Dans une équipe plus large, la propriété est généralement répartie par domaine thématique ou fonctionnalité produit.
Documentez clairement la propriété et gardez-la à jour. Lorsque la propriété change — parce qu’une personne quitte l’équipe, ou que la responsabilité d’un domaine produit change — mettez à jour les documents en même temps. La documentation non possédée devient une documentation obsolète.
Planifiez pour l’écart, pas seulement pour l’attribution : lorsque le propriétaire d’un article part ou part sans qu’aucun successeur n’a encore été nommé, la propriété devrait automatiquement passer à un plan B désigné — généralement le chef d’équipe ou le propriétaire de la catégorie mère — plutôt que de rester sans attribution jusqu’à ce que quelqu’un s’en rende compte. Un article sans propriétaire, même temporairement, est un article qui ne sera pas examiné.