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

Este post foi escrito por Rob Eisenberg, Gerente Sênior de Programas da equipe de docs.microsoft.com.

A missão da Microsoft é capacitar todas as pessoas e todas as organizações do planeta a alcançar mais. Essa foi uma de nossas considerações, pois criamos docs.microsoft.com sobre a plataforma aberta do GitHub. Hoje, vamos levá-lo para o próximo nível com a mudança para um novo sistema de comentários de documentação baseado no GitHub.

Comentários sobre conteúdo no GitHub

Embora nossa documentação tenha estado no GitHub desde o início, nosso mecanismo de comentários de conteúdo tem usado o Livefyre para comentários sobre artigos. Embora o Livefyre seja uma ótima solução de comentários, acabou sendo insuficiente para nossas necessidades específicas, que é rastrear, atribuir proprietários e manter o estado dos problemas de conteúdo gerados pelos clientes.

Exploramos uma série de caminhos para torná-lo melhor, mas uma pergunta que guiou grande parte do nosso trabalho parecia ressurgir: Se nossa documentação fosse tratada como código-fonte aberto, o que usaríamos para resolver esse problema? A resposta à pergunta parecia óbvia: de Problemas do GitHub, então começamos a experimentar a integração das APIs do GitHub mais profundamente em nossas páginas de documentação, sendo capazes de criar um sistema de comentários completo sobre a 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 rica com escritores e equipes de produtos. Vê um problema com um documento? Um exemplo de código incorreto? Uma explicação confusa? Uma omissão crítica? Basta rolar até a parte inferior da página e selecionar Fornecer comentários de documentação.

Você pode ver todos os problemas abertos e fechados associados ao documento, diretamente da própria página de documentação , dessa forma, você sempre sabe quando as coisas são corrigidas e resolvidas:

Você pode comentar e até mesmo adicionar reações a problemas importantes para você:

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

Exemplo de comentários da documentação

Digamos que você registre um problema no GitHub para um hiperlink quebrado em um artigo. Nossa equipe fará a triagem do problema, atribuirá um rótulo e atribuirá um proprietário para fazer a correção (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), que o problema foi resolvido/fechado, criando um ciclo virtuoso de comentários.

Além disso, você pode aproveitar toda a bondade padrão do GitHub, como Markdown em comentários, assinaturas para problemas individuais ou repositórios inteiros, feeds RSS da atividade da organização, @ menções, atribuições e muito mais! Acreditamos que um 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 do produto

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

Clicando em Fornecer comentários sobre o produto, agora você será levado diretamente para o site em que a equipe do produto associada à página de documentação específica manipula os comentários do produto.

Roll-Out

Talvez você esteja se perguntando quando o sistema de comentários estará ativo. Estamos pilotando há alguns meses para o do IDE do Visual Studio e a documentação da CLI do Azure . A partir de meados de fevereiro, começaremos a distribuir isso em todas as docs.microsoft.com.

Seus Comentários

Seus comentários são importantes para nós, portanto, queremos colocar esse novo sistema em suas mãos rapidamente. Embora seja nossa próxima etapa para melhorar os comentários e o engajamento em nossa plataforma, não é de forma alguma nossa última etapa. Lembre-se de expressar suas opiniões sobre as alterações no GitHubou marcar-nos no Twitter.