Nouveau système de commentaires bientôt disponible sur docs.microsoft.com
L’auteur de cette publication est Rob Eisenberg, Senior Program Manager, équipe docs.microsoft.com.
La mission de Microsoft est de permettre à chaque personne et à chaque entreprise du monde entier d’aller plus loin. Cela faisait partie de nos objectifs lorsque nous avons créé docs.microsoft.com en plus de la plateforme GitHub ouverte. Aujourd’hui, nous passons à la vitesse supérieure avec un nouveau système de commentaires de documentation basé sur GitHub.
Commentaires sur GitHub
Même si notre documentation se trouve depuis le début sur GitHub, nous utilisions jusque-là Livefyre pour permettre l’envoi de commentaires au sujet de nos articles. Bien qu’excellente, la solution Livefyre s’est avérée insuffisante pour nos besoins, qui sont notamment d’effectuer le suivi des problèmes signalés, de les affecter aux membres de notre équipe et de gérer leur résolution.
Nous avons exploré un certain nombre de voies pour l’améliorer, mais une question qui a guidé la majeure partie de notre travail semblait réapparaître : Si notre documentation est traitée comme du code open source, que doit-on utiliser pour résoudre ce problème ? La réponse à la question semblait évidente : GitHub Issues, nous avons donc commencé à essayer d’intégrer les API GitHub plus étroitement dans nos pages de documentation, ce qui nous a permis de créer un système de commentaires complet sur l’infrastructure GitHub.
Avec le nouveau système, vous pouvez désormais signaler des problèmes GitHub directement à partir d’une page de contenu, ce qui vous permet de mieux communiquer avec les auteurs des articles et les équipes produit. Vous constatez une erreur dans un document ? Un exemple de code incorrect ? Une explication prêtant à confusion ? Une omission pouvant avoir de graves conséquences ? Il vous suffit d’accéder au bas de la page et de sélectionner le lien pour fournir des commentaires sur la documentation.
Tous les problèmes relatifs à un document, qu’ils soient résolus ou en cours de résolution, sont visibles directement dans la page de documentation. De cette façon, vous êtes toujours informé lorsqu’un problème est résolu :
Vous pouvez commenter et même réagir aux problèmes qui vous intéressent :
À présent, les employés Microsoft peuvent tirer profit de la puissance de GitHub pour trier, planifier et résoudre les problèmes signalés. Quelle que soit l’étape en cours, vous êtes toujours au courant !
Exemple de commentaires sur la documentation
Supposons que vous signalez un problème GitHub sur un lien hypertexte d’un article. Notre équipe va classifier le problème, lui donner un nom et l’affecter au membre de l’équipe chargé de le résoudre (ou de répondre aux questions). Lorsque la personne chargée de résoudre le problème envoie une demande de tirage (pull request) qui corrige le problème, vous recevez une notification (en fonction de vos paramètres de notification GitHub) vous informant que le problème a été résolu ou fermé, créant ainsi un cercle vertueux de commentaires.
De plus, vous pouvez tirer parti de toutes les fonctionnalités standard de GitHub, telles que le Markdown dans les commentaires, les abonnements à certains problèmes ou à des dépôts entiers, les flux RSS concernant les activités de l’organisation, les mentions @, les destinataires, et bien plus encore ! Nous pensons qu’une meilleure intégration de cet outil open source permettra d’agrandir la communauté et de favoriser la collaboration.
Séparation des commentaires produit
L’un des problèmes du système précédent était que les commentaires concernant les produits n’étaient pas séparés des commentaires concernant la documentation. Il était donc très difficile d’effectuer le triage et le suivi des commentaires, puisque ceux-ci n’étaient pas nommés de la même manière. Nous avons décidé de corriger ce problème en créant une séparation claire entre les deux :
Quand vous cliquez sur le lien pour fournir des commentaires sur le produit, vous êtes désormais dirigé vers le site où l’équipe produit associée à la page de documentation gère les commentaires produit.
Déploiement
Vous vous demandez peut-être quand sera disponible le nouveau système de commentaires. Il y a quelques mois, nous avons mis en place une version pilote de ce système pour l’IDE Visual Studio et la documentation Azure CLI. À la mi-février, nous déploierons le système sur l’ensemble du site docs.microsoft.com.
Vos commentaires
Vos commentaires nous sont très précieux, c’est pourquoi nous voulons mettre ce système à votre disposition le plus tôt possible. Ce changement a pour but d’améliorer le système de commentaires sur notre plateforme et de favoriser l’engagement utilisateur. Sachez, toutefois, que nous ne nous arrêterons pas là. N’hésitez pas à nous donner votre avis sur les changements sur GitHub ou sur Twitter.