Ler em inglês

Partilhar via


Contribuindo para a documentação do HoloLens

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

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

Esta página abrange as etapas básicas e diretrizes para contribuir e links para Markdown básicos. Obrigado pela sua contribuição!

Acordos de recompra disponíveis

Nome do repositório URL
HoloLens MicrosoftDocs/HoloLens
Realidade mista MicrosoftDocs/ de realidade mista
Guia de entusiastas de RV MicrosoftDocs/mixed-reality/enthusiast-guide

Antes de começar

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

Nota

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

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

  • Crie uma senha forte para sua conta do GitHub.
  • Habilite autenticação de dois fatores.
  • Guarde os códigos de recuperação num local seguro.
  • Atualize suas configurações de perfil público .
    • Defina o seu nome e considere definir o seu de e-mail público para Não mostrar o meu endereço de e-mail.
    • Recomendamos que carregue uma imagem de perfil porque é apresentada uma miniatura nos artigos do Microsoft Learn para os quais contribui.
  • Se você planeja usar a linha de comando, considere configurar Git Credential Manager para Windows. Desta forma, não terá de introduzir a sua palavra-passe sempre que fizer uma contribuição.

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

Editar um artigo existente

Use o fluxo de trabalho a seguir para fazer atualizações para um artigo existente via GitHub em um navegador da Web:

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

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

    Editar um artigo.

    Isso bifurcará automaticamente uma ramificação descartável da ramificação padrão, principal.

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

  4. Atualizar 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 visualizado. Os títulos das páginas são usados para SEO e indexação, por isso não altere o título a menos que seja necessário (embora isso seja menos crítico antes que a documentação se torne pública).
    • descrição: Escreva uma breve descrição do conteúdo do artigo, o que impulsiona o SEO e a descoberta.
    • autor: Se você for o proprietário principal da página, adicione seu alias do GitHub aqui.
    • ms.author: Se você for o proprietário principal da página, adicione seu alias da Microsoft aqui (você não precisa @microsoft.com, apenas o alias).
    • ms.date: atualize a data se estiver adicionando conteúdo importante à página, mas não para correções como esclarecimento, formatação, gramática ou ortografia.
    • palavras-chave: As palavras-chave ajudam no SEO (Search Engine Optimization). Adicione palavras-chave, separadas por uma vírgula e um espaço, que sejam específicas do seu artigo, mas sem pontuação após a última palavra-chave da 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 tiver concluído as edições do artigo, desloque-se para baixo e selecione Propor alteração de ficheiro.

  6. Na página seguinte, selecione Criar solicitação pull para mesclar sua ramificação criada automaticamente na ramificação 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 mudar o nome ou eliminar um artigo existente, certifique-se de que adiciona 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 a .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. Certifique-se de que o caminho começa com o docset (neste caso, hololens) e inclui a extensão de arquivo .md.

  • O redirect_url é o URL público relativo do artigo antigo para o novo artigo. Certifique-se de que este de URL não contém.md e começa com /, pois refere-se ao URL público e não ao caminho do repositório. É permitido criar links para uma seção dentro do novo artigo usando #section. Você também pode usar um caminho absoluto para outro site aqui, se necessário.

  • redirect_document_id indica se você gostaria de 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 visualizações de página e classificações, serão transferidos para o artigo de destino. Faça isso se o redirecionamento for principalmente um renome, e não um ponteiro para artigo diferente que cobre apenas parte do mesmo conteúdo.

Se você adicionar um redirecionamento, certifique-se de excluir o arquivo antigo também.

Criar um novo artigo

Use o fluxo de trabalho a seguir para criar novos artigos no repositório de documentação via GitHub em um navegador da Web:

  1. Crie uma bifurcação fora da ramificação padrão, principal, do MicrosoftDocs/hololens usando o botão Fork no canto superior direito.

    Fork a ramificação padrão, atualmente chamada de

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

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

    Nomeie sua nova página.

    Importante

    Certifique-se de criar o novo artigo a partir 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 Editando um artigo existente.

  6. Escreva o conteúdo do artigo usando noções básicas de 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 Nova solicitação pull e mescle a ramificação principal da bifurcação no MicrosoftDocs/hololens principal (verifique se a seta está apontando para o destino correto).

    Crie pull request de sua bifurcação no MicrosoftDocs/hololens.

Noções básicas de Markdown

Os seguintes recursos irão ajudá-lo a aprender a editar a documentação usando a linguagem Markdown:

Adicionar tabelas

Devido ao estilo das tabelas no Microsoft Learn, elas não terão bordas ou estilos personalizados, mesmo se você tentar CSS embutido. Parecerá funcionar por um curto período de tempo, mas eventualmente a plataforma retirará o estilo da mesa. Por isso, planeie com antecedência e mantenha as suas mesas simples. Aqui está um site que facilita as tabelas de Markdown: [Tables Generator]](https://www.tablesgenerator.com/markdown_tables).

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

Adicionar imagens

Você precisará carregar suas imagens para a pasta "hololens/images" no repositório e, em seguida, consultá-las adequadamente no artigo. As imagens aparecerão automaticamente em tamanho real, o que significa que imagens grandes preencherão toda a largura do artigo. Recomendamos pré-dimensionar suas imagens antes de enviá-las. A largura recomendada é 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 para seu repositório bifurcado antes da fusão. Portanto, se você planeja adicionar imagens a um artigo, precisará usar o Visual Studio Code para adicionar as imagens à pasta "imagens" da bifurcação primeiro ou certifique-se de ter feito o seguinte em um navegador da Web:

  1. Forked o repositório MicrosoftDocs/hololens.
  2. Editou o artigo na sua bifurcação.
  3. Carregue as imagens que está a referenciar no seu artigo para a pasta "hololens/images" na sua bifurcação.
  4. Criou um de solicitação pull para mesclar sua bifurcação na ramificação principal do do MicrosoftDocs/hololens.

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

Pré-visualizar o seu trabalho

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

Nota

A pré-visualização das 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 na ramificação padrão, principal, você poderá revisar o conteúdo antes que ele se torne público em </hololens?branch=main>. Encontre o seu artigo utilizando o índice na coluna da esquerda.

Edição no navegador versus edição com um cliente de desktop

Editar no navegador é a maneira mais fácil de fazer alterações rápidas, no entanto, existem algumas desvantagens:

  • Você não recebe verificação ortográfica.
  • Você não obtém nenhum link inteligente para outros artigos (você tem que 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 de área de trabalho como Visual Studio Code com algumas extensões úteis ao contribuir.

Usando o Visual Studio Code

Pelas razões listadas acima, você pode preferir usar um cliente de desktop para editar a documentação em vez de um navegador da Web. Recomendamos o uso do Visual Studio Code.

Configuração

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

  1. Em um navegador da Web:
    1. Instale Git para o seu PC.
    2. Instale Visual Studio Code.
    3. Fork MicrosoftDocs/hololens se ainda não o fez.
    4. Na bifurcação, selecione Clone ou faça o download e copie o URL.
  2. Crie um clone local da sua bifurcação no Visual Studio Code:
    1. No menu Exibir, selecione Paleta de comandos.
    2. Digite "Git: Clone".
    3. Cole o URL copiado.
    4. Escolha onde salvar o clone no seu PC.
    5. Selecione de repositório Abrir no pop-up.

Edição de documentação

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

Nota

Todas as orientações para edição de e criação de artigos, e as noções básicas de edição Markdown, de cima se aplica ao usar o Visual Studio Code também.

  1. Certifique-se de que o garfo clonado está atualizado com o repositório oficial.

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

      Sincronize as alterações do MicrosoftDocs/hololens para a sua bifurcação.

    2. No Visual Studio Code, selecione o botão de sincronização para sincronizar sua bifurcação recém-atualizada com o clone local.

      Clique na imagem do botão de sincronização.

  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 no Explorer.

      Escolha

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

      Escolha Controle do código-fonte

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

      Clique no botão de sincronização.

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

    Crie pull request de sua bifurcação no MicrosoftDocs/hololens.

Extensões úteis

As seguintes extensões de código do Visual Studio são úteis ao editar a documentação:

  • Docs Markdown Extension for Visual Studio Code - Use Alt+M para exibir um menu de opções de criação do Microsoft Learn como:

    • Pesquise e faça referência às imagens que carregou.
    • Adicione formatação como listas, tabelas e textos explicativos como >[!NOTE].
    • Pesquise e faça referência a links internos e marcadores (links para seções específicas dentro de uma página).
    • Os erros de formatação são realçados (passe o rato sobre o erro para saber mais).
  • Code Spell Checker - palavras com erros ortográficos serão sublinhadas; Clique com o botão direito do rato numa palavra com erros ortográficos para a alterar ou guardar no dicionário.