Comment une équipe de documentation a corrigé les bonnes pages en le demandant sur la page elle-même

Un projet open-source a une bonne documentation et un vrai problème : le guide d'installation est subtilement erroné. Une étape a changé il y a deux versions, et maintenant les nouveaux venus restent bloqués au même point. Les gens le remarquent — il y a des grognements sur les réseaux sociaux et quelques questions confuses dans le chat de la communauté — mais les mainteneurs ne peuvent agir sur rien de tout cela, car aucune des plaintes ne précise **quelle page**. « Votre documentation n'est pas à jour » est un sentiment, pas un rapport de bug. L'étape erronée reste donc là pendant des mois, repoussant silencieusement chaque nouvel utilisateur qui essaie de démarrer. La documentation vit ou meurt grâce à cette boucle : un lecteur tombe sur un passage confus ou erroné, indique exactement où aux mainteneurs, et les mainteneurs le corrigent. Brisez le « exactement où » et toute la boucle s'arrête. ## Le problème : les retours sans emplacement sont du bruit Les lecteurs sont prêts à aider. Ils vous diront avec plaisir qu'une page est confuse. Ce qu'ils ne feront pas, c'est l'archéologie nécessaire pour rendre cette aide exploitable — copier l'URL, trouver le bon canal de contact, décrire le problème, et noter quelle section et quelle version. Cela fait beaucoup d'étapes pour quelqu'un qui essaie d'apprendre votre outil, pas d'auditer votre documentation. Les retours qui arrivent sont donc dépouillés de la seule chose qui les rend utiles : l'emplacement. Un mainteneur lisant « la documentation de l'API est erronée » a des centaines de pages et aucune idée de l'endroit où chercher. Un problème GitHub aide, mais il demande à un lecteur occasionnel d'avoir un compte, de comprendre votre modèle de problème, et de changer totalement de contexte pour sortir de la documentation — des frictions qui filtrent la plupart des retours spontanés, qui sont exactement les retours qui permettent de détecter les petites erreurs à fort impact. Le résultat est un déséquilibre étrange : de nombreux lecteurs remarquent des problèmes, mais presque aucun n'est signalé sous une forme que vous pouvez corriger. ## La solution : un lien « Signaler un problème » par page Placez un petit lien **Signaler un problème avec cette page** dans le pied de page de chaque page de documentation. C'est un lien `mailto:`, et son astuce est qu'il pré-remplit le chemin de la page actuelle dans le sujet et le corps. Le lecteur clique, son e-mail s'ouvre avec l'emplacement déjà capturé, et tout ce qu'il ajoute, c'est ce qui n'allait pas. Comme la documentation est généralement construite à partir d'un modèle ou d'un générateur de site statique, vous pouvez injecter le chemin automatiquement. Dans un site basé sur des modèles, insérez la variable de la page directement dans le lien : ```html <a href="mailto:docs@yourproject.dev?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> Signaler un problème avec cette page </a> ``` Ou définissez-le avec une ligne de script pour qu'il fonctionne sur n'importe quelle page sans utiliser de modèle : ```html <a id="docs-issue" href="#">Signaler un problème avec cette page</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:docs@yourproject.dev' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` Le générateur de ce site produit le lien encodé ; le script ne fait qu'échanger le chemin en direct. Désormais, chaque signalement nomme la page exacte dans son sujet, et un mainteneur peut accéder directement au fichier source. ## Pourquoi le signalement sur la page vaut mieux qu'un outil de suivi de problèmes pour cela Un outil de suivi de problèmes est le bon endroit pour une correction, mais une mauvaise porte d'entrée pour les retours. Il exige un compte, un changement de contexte et une familiarité avec votre processus — des obstacles qui rebutent le lecteur occasionnel qui vient de repérer une faute de frappe dans un exemple de code. Le lien `mailto:` rencontre les lecteurs là où la confusion se produit réellement : sur la page, en un clic, sans compte. Il capture la longue traîne des petites corrections qui ne survivraient jamais au voyage vers un outil de suivi. Les deux fonctionnent bien ensemble. Les rapports arrivent par e-mail, pré-étiquetés avec la page ; un mainteneur les trie et n'ouvre des problèmes dans l'outil de suivi que pour ceux qui valent la peine d'être suivis. Vous bénéficiez de la faible friction de l'e-mail à l'entrée et de la rigueur d'un outil de suivi à la sortie. ## Mise en place 1. Choisissez une boîte de réception pour la documentation, telle que `docs@`, que les mainteneurs surveillent. 2. Dans le générateur, définissez le destinataire, un sujet « Docs issue: [chemin de la page] », et un corps de message qui demande ce qui ne va pas et ce qui aiderait. 3. Ajoutez le lien au pied de page de votre modèle, en injectant le chemin avec la variable de page de votre générateur ou le petit script ci-dessus. 4. Routez le courrier entrant par la balise de sujet « Docs issue: » pour que les rapports atterrissent au même endroit. 5. Bouclez la boucle : lorsque vous corrigez une page signalée, une réponse d'une ligne au lecteur transforme un rapport de bug en bonne volonté. ## Ce que cela fait gagner Le premier gain est **le temps passé par les mainteneurs à localiser les problèmes**. Lorsque chaque signalement nomme la page, vous sautez le travail de détective et passez directement à la correction. Un signalement qui était auparavant un « quelque chose ne va pas quelque part » inexploitable devient une modification de deux minutes. Le second est **moins d'utilisateurs bloqués**. Les erreurs de documentation s'accumulent : une étape d'installation erronée ne pose pas problème qu'une seule fois, elle fait échouer chaque nouvel arrivant jusqu'à ce que quelqu'un la corrige. Raccourcir le temps entre « un lecteur remarque » et « un mainteneur sait exactement où » signifie que chaque mauvais passage repousse beaucoup moins de personnes. Pour un outil qui se développe par l'adoption, débloquer les nouveaux arrivants est un facteur de croissance. Le troisième est **le volume et la franchise des retours**. Comme le signalement prend un clic et ne nécessite aucun compte, plus de lecteurs le font — y compris ceux qui n'ouvriraient jamais un problème dans l'outil de suivi. Vous êtes informé des petites erreurs embarrassantes qui sapent la confiance, et vous en entendez parler pendant qu'elles ont encore de l'importance. ## Rendre cela encore meilleur - Pré-remplissez la **version de la documentation ou le commit** à côté du chemin, afin de pouvoir dire si un rapport est antérieur à une réécriture récente. - Ajoutez le lien aux **pages 404** de votre documentation, où une page manquante est en soi un signal utile. - Gardez l'adresse **masquée** pour que les robots ne la récoltent pas sur des milliers de pages publiques. - Offrez une alternative visible pour les lecteurs sans application de messagerie par défaut, comme une adresse en texte brut ou un lien vers un outil de suivi. ## Points clés à retenir - Les retours sur la documentation sans emplacement sont du bruit ; les lecteurs font rarement l'effort d'en joindre un. - Un lien `mailto:` « Signaler un problème » par page pré-remplit le chemin exact, rendant chaque rapport exploitable. - L'e-mail sur la page capture les corrections occasionnelles qu'un outil de suivi filtre, puis alimente l'outil de suivi pour de vraies corrections. - Cela fait gagner du temps aux mainteneurs, débloque plus rapidement les nouveaux arrivants et fait ressortir les petites erreurs qui coûtent silencieusement de la confiance. Créez votre propre lien de retour sur la documentation dans le [générateur](/#generator), ou copiez la configuration ci-dessous.