Visão geral do guia de colaborador da documentação do Microsoft Learn

  • Artigo

Bem-vindo ao guia de colaborador da documentação do Microsoft Learn!

Compartilhar sua experiência com outras pessoas no Microsoft Learn ajuda todos a alcançar mais. Use as informações neste guia para publicar um novo artigo no Microsoft Learn ou fazer atualizações em um artigo publicado existente.

Vários dos conjuntos de documentação da Microsoft são de software livre e estão hospedados no GitHub. Nem todos os conjuntos de documentos são integralmente de software livre, porém muitos têm repositórios públicos, em que é possível sugerir alterações por meio de PR (solicitações de pull). Essa abordagem de software livre otimiza e aprimora a comunicação entre os engenheiros de produto, as equipes de conteúdo e os clientes, além de apresentar outras vantagens:

  • Os repositórios de software livre contam com planejamento aberto para permitir comentários dos usuários sobre quais documentos são mais necessários.
  • Os repositórios de software livre contam com análise aberta para possibilitar a publicação do conteúdo mais útil logo na primeira versão.
  • Os repositórios de software livre contam com atualização aberta para facilitar o aprimoramento contínuo do conteúdo.

A experiência do usuário no Microsoft Learn integra fluxos de trabalho do GitHub diretamente para facilitar ainda mais. Comece editando o documento que você está exibindo. Ou então, colabore analisando novos tópicos ou criando registros de problemas de qualidade.

Importante

Todos os repositórios publicados no Microsoft Learn adotaram o Código de Conduta do Microsoft Open Source ou o Código de Conduta do .NET Foundation. Para obter mais informações, consulte Perguntas frequentes sobre código de conduta. Entre em contato com opencode@microsoft.com ou conduct@dotnetfoundation.org com perguntas ou comentários.

Correções secundárias ou esclarecimentos sobre documentação e exemplos de código em repositórios públicos são abordados pelos Termos de Uso do learn.microsoft.com. Quando há alterações novas ou significativas, é gerado um comentário na PR, pedindo que você envie um CLA (Contrato de Licença de Contribuição) online caso não seja um funcionário da Microsoft. Para analisarmos ou aceitarmos sua PR, primeiro preencha o formulário online.

Edições rápidas na documentação

Com as edições rápidas, ficou mais fácil relatar e corrigir pequenos erros e omissões na documentação. Apesar de todos os esforços, pequenos erros gramaticais e ortográficos aparecem em nossos documentos publicados. Embora você possa criar registros de problemas para relatar erros, é mais fácil e rápido criar uma PR para corrigir o problema, quando a opção estiver disponível.

  1. Algumas páginas de documentos permitem a edição do conteúdo diretamente no navegador. Se esse for o caso, você verá o botão Editar, como mostrado abaixo. Escolhendo Editar (ou o equivalente), você será levado para o arquivo de origem no GitHub.

    Localização do artigo de edição.

    Se o botão Editar não for exibido, isso significará que o conteúdo não está aberto para contribuições públicas. Algumas páginas são geradas (por exemplo, por meio da documentação embutida no código) e precisam ser editadas no projeto a que pertencem.

  2. Selecione o ícone de lápis para editar o artigo. Se o ícone do lápis estiver acinzentado, você precisará fazer logon em sua conta do GitHub ou criar uma.

    Localização do fork e ícone do lápis de edição.

  3. Edite o arquivo no editor da Web. Escolha a guia Pré-visualização para verificar a formatação das alterações.

  4. Quando terminar de editar, role até a parte inferior da página. Na área Propor alterações, insira um título e uma descrição opcional para as alterações. O título será a primeira linha da mensagem de confirmação. Selecione Propor alterações para criar um branch em seu fork e confirmar suas alterações:

    Propor e confirmar alterações de arquivos.

  5. Agora que você propôs e confirmou suas alterações, solicite aos proprietários do repositório que eles "efetuem pull" dessas alterações no repositório. Isso é feito com o que denominamos como "PR" (solicitação de pull). Quando você seleciona Propor alterações, uma nova página semelhante à seguinte é exibida:

    Comparar alterações e criar solicitação de pull.

    Selecione Criar solicitação de pull. Em seguida, insira um título e uma descrição para a PR e selecione Criar solicitação de pull. Se você for novo no GitHub, confira Sobre solicitações de pull para saber mais.

  6. É isso! Membros da equipe de conteúdo analisarão e mesclarão sua PR quando for aprovada. Você poderá receber um feedback solicitando alterações.

A interface do usuário de edição do GitHub responde às suas permissões no repositório. As imagens anteriores são exibidas para os colaboradores que não têm permissões de gravação no repositório de destino. O GitHub cria automaticamente um fork para o repositório de destino em sua conta. O nome de fork recém-criado tem o formato GitHubUsername/RepositoryName por padrão. Se você tiver acesso de gravação ao repositório de destino, como seu fork, o GitHub criará um branch nele. O nome do branch tem o formato padrão patch-n e usa um identificador numérico para o branch do patch.

Usamos solicitações de pull para todas as alterações, até mesmo para colaboradores que têm acesso de gravação. A maioria dos repositórios protege o branch padrão para que as atualizações sejam enviadas como PRs.

A experiência de edição no navegador é a melhor para alterações secundárias ou esporádicas. Se fizer grandes colaborações ou usar recursos avançados do Git (como gerenciamento de branch ou resolução avançada de conflitos de mesclagem), você precisará criar um fork do repositório e trabalhar localmente.

Observação

A maioria das documentações localizadas não oferece a capacidade de editar ou fornecer comentários por meio do GitHub. Para fornecer comentários sobre conteúdo localizado, use https://aka.ms/provide-feedback o formulário.

Examinar as solicitações de pull em aberto

Você pode ler novos tópicos antes de eles serem publicados, verificando a fila de PR aberta. As revisões seguem o processo do fluxo do GitHub. Você pode ver as atualizações propostas ou novos artigos em repositórios públicos. Revise-os e adicione seus comentários. Examine qualquer um dos nossos repositórios do Microsoft Learn e verifique as PRs abertas para áreas que lhe interessam. Os comentários da comunidade sobre atualizações propostas ajudam toda a comunidade.

Criar registros de problemas de qualidade

Nossos documentos estão sempre em evolução. E, com bons registros de problemas, conseguimos concentrar nossos esforços no que é mais importante para a comunidade. Quanto mais detalhes você fornecer, mais útil será o registro do problema. Diga-nos quais informações você buscou. Diga-nos quais termos de pesquisa você usou. Se você não souber como começar, diga-nos como deseja explorar novas tecnologias.

Muitas páginas da documentação da Microsoft têm uma seção de Comentários na parte inferior onde você pode escolher para enviar comentários sobre o produto ou comentários sobre o conteúdo e, assim, rastrear problemas específicos daquele artigo.

Os registros de problemas é o pontapé inicial. A equipe de conteúdo responderá a esses registros de problemas com ideias sobre o que podemos adicionar e pedirá suas opiniões. Quando criarmos um rascunho, pediremos a você que revise a solicitação de pull.

Aumente seu engajamento

Outros tópicos neste guia ajudam você a começar a contribuir de forma produtiva para o Microsoft Learn. Eles explicam como trabalhar com repositórios do GitHub, ferramentas markdown e extensões usadas no conteúdo do Microsoft Learn.