Um novo sistema de comentários está chegando ao docs.microsoft.com

Esta postagem foi redigida por Rob Eisenberg, Gerente de Programa Sênior da equipe do docs.microsoft.com.

A missão da Microsoft é capacitar cada pessoa e organização no planeta a conquistar cada vez mais. Essa foi uma das nossas considerações, visto que criamos o docs.microsoft.com como um complemento à plataforma aberta do GitHub. Hoje, estamos avançando com a mudança para um novo sistema de comentários de documentação baseada no GitHub.

Comentários sobre o conteúdo no GitHub

Embora nossa documentação esteja no GitHub desde o início, nosso mecanismo de comentários sobre o conteúdo utiliza o Livefyre para fazer comentários sobre artigos. Apesar de o Livefyre ser uma ótima solução de comentários, ele acabou sendo insuficiente para nossas necessidades específicas, que são acompanhar, atribuir proprietários e manter o status dos problemas de conteúdo gerados pelos clientes.

Tentamos vários meios de aprimorá-lo, mas uma pergunta que direcionou grande parte do trabalho ficou ressurgindo: se a documentação fosse tratada como código-fonte aberto, o que usaríamos para resolver esse problema? A resposta parecia óbvia: Problemas do GitHub. Então começamos a experimentar uma integração maior das APIs do GitHub às nossas páginas de documentação, podendo criar um sistema de comentários completo com base na infraestrutura do GitHub.

Com o novo sistema, agora você pode criar problemas do GitHub diretamente de uma página de conteúdo, o que permite que você interaja de uma maneira muito mais avançada com os gravadores e as equipes de produtos. Encontrou um problema em um documento? Um exemplo de código incorreto? Uma explicação confusa? Uma omissão crítica? Basta rolar até o final da página e selecionar Fazer comentários sobre a documentação.

Você pode ver todos os problemas em aberto e resolvidos associados ao documento diretamente da página da documentação. Dessa forma, você estará sempre informado quando os problemas forem solucionados:

Você pode comentar e até mesmo adicionar reações aos problemas que são importantes para você:

Agora, os funcionários da Microsoft podem aproveitar todo o potencial dos problemas do GitHub para fazer a triagem, responder, planejar e corrigir problemas reportados – e você sempre terá visibilidade do processo!

Exemplo de comentários sobre a documentação

Digamos que você arquive um problema do GitHub para um hiperlink desfeito em um artigo. Nossa equipe fará a triagem do problema, atribuirá um rótulo e um proprietário para corrigi-lo (ou fazer perguntas de acompanhamento). Quando o proprietário enviar uma solicitação de pull que corrija o problema, você será notificado (com base nas configurações de notificação do GitHub) de que o problema foi resolvido, criando um ciclo virtuoso de comentários.

Além disso, você pode aproveitar todas as vantagens do padrão do GitHub, como o Markdown em comentários, assinaturas de problemas individuais ou repositórios inteiros, RSS feeds da atividade da organização, @menções, destinatários e muito mais! Acreditamos que o nível mais profundo de integração de ferramentas de software livre promoverá novas oportunidades de crescimento e colaboração da comunidade.

Separação de comentários sobre o produto

Um dos problemas com o sistema anterior era a combinação entre os comentários sobre o produto e a documentação em um fluxo – era extremamente difícil fazer a triagem e o acompanhamento, quando nem todos os itens eram rotulados de forma consistente. Demos um passo à frente para corrigir esse problema, criando uma maneira clara de separar os dois:

Ao clicar em Fazer comentários sobre produto, você será direcionado ao site em que a equipe do produto associada à página de documentação específica lida com os comentários sobre o produto.

Reverter

Você deve estar se perguntando quando o sistema de comentários estará disponível. Já estamos testando o sistema há alguns meses para a documentação do Visual Studio IDE e da CLI do Azure. A partir de meados de fevereiro, começaremos a implementá-lo em todos os docs.microsoft.com.

Seus comentários

Seus comentários são muito importantes para nós. Por isso, queremos disponibilizar esse sistema para você sem demora. Embora esta seja nossa próxima etapa para melhorar os comentários e a participação em nossa plataforma, ela não será a última. Dê sua opinião sobre as alterações no GitHub ou marque-nos no Twitter.