Um Novo Sistema de Comentários está a Chegar para docs.microsoft.com

Esta mensagem foi escrita por Rob Eisenberg, Gestor de Programa Sénior na equipa do docs.microsoft.com.

A Microsoft tem como missão permitir que todas as pessoas e organizações no mundo possam ir mais além. Esta foi uma das preocupações que tivemos ao criar o docs.microsoft.com com base na plataforma aberta GitHub. Hoje, vamos avançar para o próximo nível ao mudar para um novo sistema de feedback de documentação baseado no GitHub.

Feedback Sobre Conteúdos no GitHub

Apesar de a nossa documentação se encontrar no GitHub desde o princípio, o nosso mecanismo de feedback sobre conteúdos tem utilizado o Livefyre para comentários em artigos. Embora o Livefyre seja uma ótima solução para comentários, tornou-se insuficiente para as nossas necessidades específicas, nomeadamente controlar, atribuir proprietários e fornecer atualizações sobre problemas relativos a conteúdos comunicados pelos clientes.

Explorámos várias vias para o melhorar, mas uma pergunta que guiou grande parte do nosso trabalho parecia ressurgir: se a nossa documentação fosse tratada como open source código, o que utilizaríamos para resolver este problema? A resposta à pergunta parecia óbvia: Problemas do GitHub, por isso começámos a experimentar integrar as APIs do GitHub mais profundamente nas nossas páginas de documentação, conseguindo criar um sistema de comentários completo sobre a infraestrutura do GitHub.

Com o novo sistema, já pode comunicar problemas no GitHub diretamente de uma página de conteúdos, o que permite uma melhor interação com os programadores e as equipas dos produtos. Detetou um problema com um documento? Um exemplo de código errado? Uma explicação confusa? Uma omissão importante? Desloque-se até à parte inferior da página e selecione Give documentation feedback (Dar feedback sobre a documentação).

Pode ver todos os problemas associados ao documento diretamente na respetiva página. Deste modo, saberá sempre quando é que estes problemas já foram corrigidos e resolvidos:

Pode comentar e até adicionar reações aos problemas que achar importantes:

Agora, os colaboradores da Microsoft podem tirar o máximo partido do GitHub Issues para selecionar, responder, planear e corrigir os problemas comunicados e você poderá ver todo o processo!

Exemplo de feedback sobre documentação

Imaginemos que comunica um problema no GitHub sobre uma ligação num artigo que não funciona. A nossa equipa irá fazer uma triagem do problema, atribuir uma etiqueta e atribuir um proprietário para proceder à correção do problema (ou para fazer perguntas de seguimento). Quando o proprietário enviar um pedido Pull para corrigir o problema, irá receber uma notificação (com base nas suas definições de notificação do GitHub) a indicar que o problema foi resolvido/encerrado, criando assim um ciclo positivo de feedback.

Além disso, pode tirar partido de todas as funcionalidades normais do GitHub, como a utilização de linguagem Markdown em comentários, subscrições de problemas específicos ou repositórios inteiros, feeds RSS da atividade da organização, @menções, detentores e muito mais! Acreditamos que uma integração mais aprofundada de ferramentas open source vai ajudar a promover novas oportunidades de colaboração e crescimento da comunidade.

Separação de Feedback Sobre Produtos

Um dos problemas com o sistema anterior residia na mistura de feedback de produtos e documentação num único fluxo, o que tornava a triagem e o seguimento muito difíceis quando a totalidade dos itens não era identificada de modo consistente. Decidimos dar um passo em frente na correção deste problema ao criar uma forma clara de separar os dois tipos de feedback:

Agora, ao clicar em Give product feedback (Dar feedback sobre o produto), será direcionado para o site onde a equipa do produto associada à página da documentação específica gere o feedback sobre o produto.

Implementação

Provavelmente estará a perguntar-se sobre quando é que o sistema de feedback estará disponível. Temos estado a testá-lo durante alguns meses na documentação do IDE do Visual Studio e da CLI do Azure. A partir de meados de fevereiro, começaremos a implementar este sistema em todo o docs.microsoft.com.

O seu Feedback

O seu feedback é importante para nós e, por isso, queremos colocar rapidamente este sistema à sua disposição. Embora este seja o nosso próximo passo para melhorar o feedback e a interação com a nossa plataforma, não será de todo o último. Certifique-se de que expressa as suas opiniões sobre as alterações no GitHub ou marca-nos no Twitter.