Editar a documentação do Microsoft Learn no browser

  • Artigo

Dica

Um roteiro de aprendizado passo a passo individual está disponível para este tópico.

Vários dos conjuntos de documentação da Microsoft são de software livre e estão hospedados no GitHub. Porém, nem todos os conjuntos de documentos são integralmente de software livre, pois muitos têm repositórios públicos, em que é possível sugerir alterações por meio de pull requests (PRs). Essa abordagem de código aberto simplifica e melhora a comunicação entre engenheiros de produtos, equipes de conteúdo e clientes.

As edições rápidas facilitam 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. Agradecemos sua ajuda para identificar e corrigir estes problemas!

Usamos pull requests para todas as alterações, até mesmo para contribuidores que têm acesso para gravação. A maioria dos repositórios protege o branch padrão, portanto, as atualizações devem ser enviadas como PRs.

Pré-requisito

Editar um documento no browser

  1. Navegar até a documentação que deseja editar. Algumas páginas de documentos permitem a edição do conteúdo diretamente no browser. Se esse for o caso, você verá um ícone de lápis Editar como o mostrado abaixo. Escolher o ícone de lápis Editar leva você ao arquivo de origem no GitHub.

    Screenshot of an Azure documentation article showing the edit pencil icon.

    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 na parte superior da página de arquivo do GitHub. Se o ícone de lápis estiver cinza ou não for exibido, você precisará fazer logon na sua conta do GitHub.

    Screenshot of the Azure article within GitHub,showing the edit pencil icon.

    Na parte superior do artigo, estão os metadados do artigo. Os metadados são aplicados aos artigos para geração de relatórios, capacidade de descoberta por meio de pesquisa e aspectos de condução da experiência do site. Se você estiver fazendo pequenas atualizações em um artigo publicado, provavelmente não precisará alterar os metadados.

  3. Se esta for a primeira vez que você está trabalhando neste repositório, você será solicitado a criar fork do repositório antes de propor alterações. Selecione Criar fork deste repositório para continuar.

  4. Edite o arquivo no editor da Web. Escolha a guia Preview na barra de ferramentas para verificar a formatação das suas alterações.

  5. Quando terminar de editar, selecione o botão Confirmar alterações ou Propor alterações, geralmente no canto superior direito da tela.

  6. Insira uma mensagem do commit. A mensagem do commit torna-se o título da sua PR e deve ser um breve resumo das suas alterações (por exemplo, "Corrigir erros ortográficos e gramaticais"). Opcionalmente, adicione uma descrição estendida para fornecer mais detalhes sobre suas alterações. Selecione Propor alterações:

    Screenshot of the propose changes pop-up.

  7. 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 usando uma pull request (PR). Ao selecionar Propor alterações, você verá uma página como esta:

    Screenshot of the comparing changes screen.

    Sua PR propõe alterações do seu fork e branch (representados pelos dois itens no lado direito da seta) para o fork principal e main o branch do repositório de documentação (representados pelos dois itens no lado esquerdo da seta).

    Revise suas alterações e, em seguida, selecione Criar pull request:

  8. Na página Abrir uma pull request, visualize sua PR. Você pode alterar os campos de título ou descrição, se necessário. Quando estiver pronto, selecione Criar pull request. Esta ação abre seu PR e alerta o proprietário do artigo de que você propôs uma alteração.

  9. É 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. Para conhecer em mais detalhes o processamento do seu PR, consulte Processar uma solicitação pull.

Limitações

  • A maioria dos conteúdos localizados (ou seja, traduzidos) não oferece a capacidade de editar pelo GitHub. Porém, você pode fazer comentários sobre a qualidade da tradução selecionando o botão Comentários (polegares) na parte superior da página e, depois, escolhendo o motivo da Qualidade da tradução. Você também pode deixar comentários mais específicos sobre conteúdo localizado usando o formulário Fornecer comentário.
  • A experiência de edição no browser funciona melhor para alterações menores e esporádicas. Se fizer grandes colaborações ou usar recursos avançados do Git (como gerenciamento de branches ou resolução de conflitos de mesclagem avançada), recomendamos a você criar fork do repositório e trabalhar localmente.