Ler em inglês

Compartilhar via


Contribuindo para a documentação do HoloLens

Bem-vindo à documentação do HoloLens! Todos os artigos que você criar ou editar neste repositório estarão visíveis ao público.

A documentação do HoloLens é publicada no Microsoft Learn, que usa Markdown com sabor do GitHub com recursos do Markdig. O conteúdo que você edita neste repositório é formatado em páginas estilizadas que aparecem em /hololens.

Esta página aborda as etapas e diretrizes básicas para contribuir e links para as noções básicas do Markdown. Obrigado por sua contribuição!

Repositórios disponíveis

Nome do repositório URL
HoloLens MicrosoftDocs/HoloLens
Realidade Misturada MicrosoftDocs/ de realidade misturada
Guia dos entusiastas de VR MicrosoftDocs/mixed-reality/enthusiast-guide

Antes de começar

Se você ainda não tiver uma, precisará criar uma conta do GitHub.

Observação

Se você for um funcionário da Microsoft, vincule sua conta do GitHub ao alias da Microsoft no do portal do Microsoft Open Source. Ingresse no "Microsoft" e organizações de "MicrosoftDocs".

Ao configurar sua conta do GitHub, também recomendamos estas precauções de segurança:

  • Crie uma senha forte para sua conta do GitHub.
  • Habilitar de autenticação de dois fatores.
  • Salve seus códigos de recuperação em um local seguro.
  • Atualize suas configurações de perfil público .
    • Defina seu nome e considere definir o de email público para Não mostre meu endereço de email.
    • Recomendamos que você carregue uma imagem de perfil porque uma miniatura é mostrada nos artigos do Microsoft Learn aos quais você contribui.
  • Se você planeja usar a linha de comando, considere configurar Git Credential Manager para Windows. Dessa forma, você não precisará inserir sua senha sempre que fizer uma contribuição.

O sistema de publicação está vinculado ao GitHub, portanto, essas etapas são importantes. Você será listado como autor ou colaborador de cada artigo usando seu alias do GitHub.

Editando um artigo existente

Use o seguinte fluxo de trabalho para fazer atualizações para um artigo existente por meio do GitHub em um navegador da Web:

  1. Navegue até o artigo que você deseja editar na pasta "hololens".

  2. Selecione o botão editar (ícone de lápis) no canto superior direito.

    Editar um artigo.

    Isso bifurcará automaticamente um branch descartável do branch padrão, principal.

  3. Edite o conteúdo do artigo de acordo com as noções básicas do Markdown.

  4. Atualize os metadados na parte superior de cada artigo:

    • título: título da página que aparece na guia do navegador quando o artigo está sendo exibido. Os títulos de página são usados para SEO e indexação, portanto, não altere o título, a menos que seja necessário (embora isso seja menos crítico antes que a documentação se torna pública).
    • descrição: escreva uma breve descrição do conteúdo do artigo, o que aumenta a SEO e a descoberta.
    • autor: se você for o proprietário principal da página, adicione o alias do GitHub aqui.
    • ms.author: se você for o proprietário principal da página, adicione o alias da Microsoft aqui (não é necessário @microsoft.com, apenas o alias).
    • ms.date: atualize a data se você estiver adicionando conteúdo principal à página, mas não para correções como esclarecimento, formatação, gramática ou ortografia.
    • palavras-chave: ajuda de palavras-chave em SEO (otimização do mecanismo de pesquisa). Adicione palavras-chave, separadas por uma vírgula e um espaço, que são específicas ao seu artigo, mas sem pontuação após a última palavra-chave em sua lista. Você não precisa adicionar palavras-chave globais que se aplicam a todos os artigos, pois elas são gerenciadas em outro lugar.
  5. Quando concluir as edições do artigo, role para baixo e selecione Propor alteração de arquivo.

  6. Na próxima página, selecione Criar de solicitação de pull para mesclar seu branch criado automaticamente no branch padrão, principal.

  7. Repita as etapas acima para o próximo artigo que você deseja editar.

Renomear ou excluir um artigo existente

Se a alteração renomear ou excluir um artigo existente, adicione um redirecionamento. Dessa forma, qualquer pessoa com um link para o artigo existente ainda acabará no lugar certo. Os redirecionamentos são gerenciados pelo arquivo .openpublishing.redirection.json na raiz do repositório.

Para adicionar um redirecionamento ao .openpublishing.redirection.json, adicione uma entrada à matriz redirections:

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • O source_path é o caminho relativo do repositório para o artigo antigo que você está removendo. Verifique se o caminho começa com o docset (nesse caso, hololens) e inclui a extensão de arquivo .md.

  • O redirect_url é a URL pública relativa do artigo antigo para o novo artigo. Verifique se esse de URL não contém .md e começa com /, como se refere à URL pública e não ao caminho do repositório. A vinculação a uma seção no novo artigo usando #section é permitida. Você também pode usar um caminho absoluto para outro site aqui, se necessário.

  • redirect_document_id indica se você deseja manter a ID do documento do arquivo anterior. O padrão é false. Use true se quiser preservar o valor do atributo ms.documentid do artigo redirecionado. Se você preservar a ID do documento, os dados, como exibições de página e classificações, serão transferidos para o artigo de destino. Faça isso se o redirecionamento for principalmente uma renomeação e não um ponteiro para um artigo diferente que abrange apenas alguns dos mesmos conteúdos.

Se você adicionar um redirecionamento, exclua o arquivo antigo também.

Criando um novo artigo

Use o seguinte fluxo de trabalho para criar novos artigos no repositório de documentação por meio do GitHub em um navegador da Web:

  1. Crie uma bifurcação fora do branch padrão, principal , de MicrosoftDocs/hololens usando o botão fork no canto superior direito.

    Bifurcar o branch padrão, atualmente denominado

  2. Na pasta "hololens", selecione Criar nova de arquivo no canto superior direito.

  3. Crie um nome de página para o artigo (use hifens em vez de espaços e não use pontuação ou apóstrofos) e acrescente ".md"

    Nomeie sua nova página.

    Importante

    Crie o novo artigo de dentro da pasta "hololens". Você pode confirmar isso verificando "/hololens/" na nova linha de nome de arquivo.

  4. Na parte superior da nova página, adicione o seguinte bloco de metadados:

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. Preencha os campos de metadados relevantes, conforme descrito anteriormente em Editar um artigo existente.

  6. Escreva o conteúdo do artigo usando noções básicas do Markdown.

  7. Adicione uma seção ## See also na parte inferior do artigo com links para outros artigos relevantes.

  8. Quando terminar, selecione Confirmar novo arquivo.

  9. Selecione Novo de solicitação de pull e mesclar a ramificação de principal do da bifurcação no MicrosoftDocs/hololens principal (verifique se a seta está apontando para o destino correto).

    Criar solicitação de pull da sua bifurcação para MicrosoftDocs/hololens.

Noções básicas do Markdown

Os recursos a seguir ajudarão você a aprender a editar a documentação usando o idioma Markdown:

Adicionando tabelas

Devido à forma como as tabelas são estilizadas no Microsoft Learn, elas não terão bordas ou estilos personalizados, mesmo se você tentar CSS embutido. Ele parecerá funcionar por um curto período de tempo, mas eventualmente a plataforma removerá o estilo da tabela. Portanto, planeje com antecedência e mantenha suas tabelas simples. Aqui está um site que facilita as tabelas Markdown: [Gerador de Tabelas](https://www.tablesgenerator.com/markdown_tables).

A de Extensão de Markdown do Docs para Visual Studio Code também facilita a geração de tabelas se você estiver usando Visual Studio Code (veja abaixo) para editar a documentação.

Adicionando imagens

Você precisará carregar suas imagens na pasta "hololens/imagens" no repositório e referenciá-las adequadamente no artigo. As imagens serão exibidas automaticamente em tamanho real, o que significa que imagens grandes preencherão toda a largura do artigo. É recomendável dimensionar previamente suas imagens antes de carregá-las. A largura recomendada está entre 600 e 700 pixels, embora você deva dimensionar para cima ou para baixo se for uma captura de tela densa ou uma fração de uma captura de tela, respectivamente.

Importante

Você só pode carregar imagens no repositório bifurcado antes de mesclar. Portanto, se você planeja adicionar imagens a um artigo, precisará usar o Visual Studio Code para adicionar as imagens à pasta "imagens" da sua bifurcação primeiro ou verificar se você fez o seguinte em um navegador da Web:

  1. Bifurcaram o repositório MicrosoftDocs/hololens.
  2. Editou o artigo em sua bifurcação.
  3. Carreguei as imagens que você está referenciando em seu artigo para a pasta "hololens/images" em sua bifurcação.
  4. Criou uma solicitação de pull para mesclar sua bifurcação no branch de principal do MicrosoftDocs/hololens.

Para saber como configurar seu próprio repositório bifurcado, siga as instruções para criar um novo artigo.

Visualizando seu trabalho

Durante a edição no GitHub por meio de um navegador da Web, você pode selecionar a guia Visualização perto da parte superior da página para visualizar seu trabalho antes de confirmar.

Observação

A visualização de suas alterações no Microsoft Learn só está disponível para funcionários da Microsoft.

Funcionários da Microsoft: quando suas contribuições tiverem sido mescladas no branch padrão, principal, você poderá examinar o conteúdo antes que ele se torna público em </hololens?branch=main>. Localize seu artigo usando o sumário na coluna esquerda.

Edição no navegador versus edição com um cliente da área de trabalho

A edição no navegador é a maneira mais fácil de fazer alterações rápidas, no entanto, há algumas desvantagens:

  • Você não recebe verificação ortográfica.
  • Você não obtém nenhuma vinculação inteligente a outros artigos (você precisa digitar manualmente o nome do arquivo do artigo).
  • Pode ser um incômodo carregar e referenciar imagens.

Se você preferir não lidar com esses problemas, use um cliente da área de trabalho como do Visual Studio Code com algumas extensões úteis ao contribuir.

Usando o Visual Studio Code

Pelos motivos listados acima, você pode preferir usar um cliente da área de trabalho para editar a documentação em vez de um navegador da Web. É recomendável usar do Visual Studio Code.

Configuração

Siga estas etapas para configurar o Visual Studio Code para trabalhar com este repositório:

  1. Em um navegador da Web:
    1. Instale Git para seu computador.
    2. Instale do Visual Studio Code.
    3. Fork MicrosoftDocs/hololens se ainda não tiver feito isso.
    4. Na bifurcação, selecione Clonar ou baixar e copiar a URL.
  2. Crie um clone local da bifurcação no Visual Studio Code:
    1. No menu Exibir, selecione Paleta de Comandos.
    2. Digite "Git: Clonar".
    3. Cole a URL copiada.
    4. Escolha onde salvar o clone no computador.
    5. Selecione Abrir de repositório no pop-up.

Documentação de edição

Use o seguinte fluxo de trabalho para fazer alterações na documentação com o Visual Studio Code:

Observação

Todas as diretrizes para edição e a criação de artigos e as noções básicas de de edição do Markdown, acima, também se aplicam ao usar o Visual Studio Code.

  1. Verifique se o fork clonado está atualizado com o repositório oficial.

    1. Em um navegador da Web, crie uma solicitação de pull para sincronizar alterações recentes de outros colaboradores no branch padrão do MicrosoftDocs/hololens, principal, para o seu fork (verifique se a seta está apontando para o destino correto).

      Sincronizar alterações de MicrosoftDocs/hololens para sua bifurcação.

    2. No Visual Studio Code, selecione o botão sincronizar sua bifurcação atualizada com o clone local.

      Clique na imagem do botão sincronizar.

  2. Crie ou edite artigos em seu repositório clonado usando o Visual Studio Code.

    1. Edite um ou mais artigos (adicione imagens à pasta "imagens", se necessário).

    2. Salvar alterações nodo Explorer do .

      Escolha

    3. Confirmar todas as alterações no de Controle do Código-Fonte (gravar mensagem de confirmação quando solicitado).

      escolha

    4. Selecione o botão sincronizar para sincronizar suas alterações de volta à origem (sua bifurcação no GitHub).

      clique no botão sincronizar.

  3. Em um navegador da Web, crie uma solicitação de pull para sincronizar novas alterações na bifurcação de volta para MicrosoftDocs/hololens principal (verifique se a seta está apontando para o destino correto).

    Criar solicitação de pull da sua bifurcação para MicrosoftDocs/hololens.

Extensões úteis

As seguintes extensões do Visual Studio Code são úteis ao editar a documentação:

  • Extensão markdown do Docs para Visual Studio Code – use Alt+M para exibir um menu de opções de criação do Microsoft Learn como:

    • Pesquisar e referenciar imagens que você carregou.
    • Adicione formatação como listas, tabelas e chamadas como >[!NOTE].
    • Pesquisar e referenciar links internos e indicadores (links para seções específicas em uma página).
    • Erros de formatação são realçados (passe o mouse sobre o erro para saber mais).
  • verificador ortográfico de código – palavras incorretas serão sublinhadas; clique com o botão direito do mouse em uma palavra incorreta para alterá-la ou salvá-la no dicionário.