Un nouveau système de commentaires s’docs.microsoft.com
Ce poste a été écrit par Rob Eisenberg, directeur principal du programme de l’équipe docs.microsoft.com.
La mission de Microsoft est de permettre à chaque personne et à chaque organisation sur la planète d’obtenir davantage. C’était l’un de nos points à prendre en compte, car nous construit docs.microsoft.com sur la plateforme GitHub ouverte. Aujourd’hui, nous allons passer au niveau suivant avec le passage à un nouveau système de commentaires de documentation basé sur GitHub.
Commentaires de contenu sur GitHub
Bien que notre documentation ait été sur GitHub depuis le début, notre mécanisme de commentaires de contenu utilise Livefyre pour les commentaires sur les articles. Bien que Livefyre soit une excellente solution de commentaire, elle s’est avérée insuffisante pour nos besoins spécifiques, qui consiste à suivre, affecter des propriétaires et maintenir l’état des problèmes de contenu soulevés par les clients.
Nous avons exploré un certain nombre d’avenues pour le rendre meilleur, mais une question qui a guidé une grande partie de notre travail semblait ressurface : Si notre documentation était traitée comme du code open source, qu’utiliserions-nous pour résoudre ce problème ? La réponse à la question semblait évidente : Problèmes GitHub, nous avons donc commencé à expérimenter l’intégration d’API GitHub plus profondément dans nos pages de documentation, en étant en mesure de créer un système de commentaires complet sur l’infrastructure GitHub.
Avec le nouveau système, vous pouvez désormais créer des problèmes GitHub directement à partir d’une page de contenu, ce qui vous permet d’interagir de manière beaucoup plus riche avec les rédacteurs et les équipes de produits. Consultez un problème avec un document ? Exemple de code incorrect ? Une explication déroutante ? Une omission critique ? Faites défiler vers le bas de la page et sélectionnez Envoyer des commentaires sur la documentation.
Vous pouvez voir tous les problèmes ouverts et fermés associés au document, directement à partir de la page de documentation elle-même. De cette façon, vous êtes toujours au courant lorsque les choses sont corrigées et résolues :
Vous pouvez commenter et même ajouter des réactions aux problèmes importants pour vous :
Maintenant, les employés de Microsoft peuvent tirer parti de la puissance totale des problèmes GitHub pour trier, répondre, planifier et résoudre les problèmes signalés , et vous aurez toujours une visibilité sur le processus !
Exemples de commentaires sur la documentation
Supposons que vous déposez un problème GitHub pour un lien hypertexte rompu sur un article. Notre équipe trie le problème, attribue une étiquette et attribue un propriétaire pour effectuer le correctif (ou poser des questions de suivi). Lorsque le propriétaire envoie une demande de tirage qui résout le problème, vous serez averti (en fonction de vos paramètres de notification GitHub), que le problème a été résolu/fermé, en créant un cycle de commentaires vertueux.
En outre, vous pouvez tirer parti de toutes les bonnes qualités GitHub standard, telles que Markdown dans les commentaires, les abonnements à des problèmes individuels ou à des dépôts entiers, les flux RSS de l’activité de l’organisation, @ mentions, affectations et bien plus encore ! Nous pensons que le niveau plus profond d’intégration des outils open source va favoriser la croissance et la collaboration de la communauté.
Séparation des commentaires sur les produits
L’un des problèmes liés au système précédent était le mélange entre les commentaires sur le produit et la documentation dans un flux - il était extrêmement difficile de trier et de suivre, quand tous les éléments ne sont pas étiquetés de manière cohérente. Nous avons pris un pas en avant pour résoudre ce problème en créant un moyen clair de séparer les deux :
En cliquant sur Envoyer des commentaires sur le produit, vous serez dirigé directement vers le site où l’équipe produit associée à la page de documentation spécifique gère les commentaires sur le produit.
Roll-Out
Vous vous demandez peut-être quand le système de commentaires sera en direct. Nous l’avons pilote depuis quelques mois pour le IDE Visual Studio et la documentation Azure CLI. À compter de la mi-février, nous allons commencer à déployer cette opération sur toutes les docs.microsoft.com.
Vos commentaires
Vos commentaires sont importants pour nous, donc nous voulons obtenir ce nouveau système dans vos mains rapidement. Bien qu’il s’agit de notre prochaine étape dans l’amélioration des commentaires et de l’engagement sur notre plateforme, cela n’est pas notre dernière étape. Veillez à exprimer vos réflexions sur les modifications sur GitHub, ou étiquetez-nous sur Twitter.