Contribuindo para Realidade Misturada documentação do desenvolvedor

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

Os documentos Realidade Misturada agora estão hospedados no Microsoft Learn, que usa o 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 /windows/mixed-reality.

Esta página aborda as etapas e diretrizes básicas de contribuição e links para noções básicas de Markdown. Agradecemos a sua contribuição.

Repositórios disponíveis

Nome do repositório	URL
Âncoras de Objeto do Azure	MicrosoftDocs/azure-docs/articles/object-anchors
Azure Remote Rendering	MicrosoftDocs/azure-docs/articles/remote-rendering
Âncoras Espaciais do Azure	MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens	MicrosoftDocs/HoloLens
Realidade Misturada	MicrosoftDocs/mixed-reality
Guia para entusiastas de VR	MicrosoftDocs/mixed-reality/enthusiast-guide

Antes de começar

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

Observação

Se você for um funcionário da Microsoft, vincule sua conta do GitHub ao seu alias da Microsoft no portal de Software Livre da Microsoft. Ingresse nas organizações "Microsoft" e "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.
• Habilite a 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 seu Email público para Não mostrar meu endereço de email.
  • Recomendamos que você carregue uma imagem de perfil, porque uma miniatura é mostrada nas páginas de documentos para as quais você contribui.
• Se você planeja usar a linha de comando, considere configurar o Gerenciador de Credenciais Git para Windows. Dessa forma, você não precisará inserir sua senha toda vez 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 para cada artigo usando seu alias do GitHub.

Como editar uma política existente

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

1. Navegue até o artigo que você deseja editar na pasta "mixed-reality-docs".

2. Selecione o botão editar (ícone de lápis) no canto superior direito, que bifurcará automaticamente um branch descartável do branch 'mestre'.

   

3. Edite o conteúdo do artigo de acordo com as "noções básicas de 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 de a documentação ficar pública).
   • descrição: escreva uma breve descrição do conteúdo do artigo, que aumenta a SEO e a descoberta.
   • autor: se você for o proprietário principal da página, adicione seu alias de GitHub aqui.
   • ms.author: se você for o proprietário principal da página, adicione o alias da Microsoft aqui (você não precisa @microsoft.comde , 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: as palavras-chave ajudam na SEO (otimização do mecanismo de pesquisa). Adicione palavras-chave, separadas por uma vírgula e um espaço, que são específicas para o 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. Depois de concluir as edições do artigo, role para baixo e selecione Propor alteração de arquivo.

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

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

Renomear ou excluir um artigo existente

Se sua alteração for renomear ou excluir um artigo existente, você precisará adicionar um redirecionamento. Dessa forma, qualquer pessoa com um link para o artigo existente ainda será direcionada ao 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": "mixed-reality-docs/old-article.md",
            "redirect_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 mixed-reality-docs e termina com .md.
• A redirect_url é a URL pública relativa do artigo antigo para o novo artigo. Verifique se essa URL não contém mixed-reality-docs ou .md, como se refere à URL pública e não ao caminho do repositório. É permitido vincular a uma seção dentro do novo artigo usando #section. Você também pode usar um caminho absoluto para outro site, 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 você quiser preservar o valor do atributo ms.documentid do artigo redirecionado. Se você preserva a ID do documento, os dados, como exibições de página e classificações, são transferidos para o artigo de destino. Faça isso se o redirecionamento for principalmente renomeado e não um ponteiro para um artigo diferente que abrange apenas parte do mesmo conteúdo.

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

Criando um artigo

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

1. Crie uma bifurcação fora do branch "mestre" microsoftDocs/realidade misturada (usando o botão Fork no canto superior direito).

   

2. Na pasta "mixed-reality-docs", selecione Criar novo 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 nem apóstrofos) e acrescente ".md"

   

   Importante

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

4. Na parte superior da sua 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 de acordo com as instruções na seção acima.

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 arquivo.

9. Selecione Nova solicitação de pull e mescle o branch 'mestre' do fork em MicrosoftDocs/mixed-reality 'master' (verifique se a seta está apontando da maneira correta).

   

Noções básicas de markdown

Os seguintes recursos ajudarão você a aprender a editar a documentação usando a linguagem de Markdown:

• Noções básicas de Markdown
• Pôster de referência de Markdown-at-a-glance
• Recursos adicionais para gravar Markdown para Microsoft Learn

Adicionando tabelas

Devido à maneira como a documentação técnica da Microsoft define as tabelas, elas não terão bordas ou estilos personalizados, mesmo que você experimente o CSS embutido. Essa alternativa 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.

A extensão de Markdown de documentos para o Visual Studio Code também facilitará a geração de tabelas se você estiver usando o Visual Studio Code (veja abaixo) para editar a documentação.

Adição de imagens

Você precisará carregar suas imagens na pasta "mixed-reality-docs/images" no repositório e referenciá-las adequadamente no artigo. As imagens aparecerão automaticamente em tamanho normal, o que significa que imagens grandes preencherão toda a largura do artigo. Recomendamos dimensionar previamente suas imagens antes de carregá-las. A largura recomendada é entre 600 e 700 pixels, embora você deva ampliá-las ou reduzi-las 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 de mesclar. Portanto, se você planeja adicionar imagens a um artigo, precisará usar o Visual Studio Code para adicionar as imagens à pasta "images" de seu fork primeiro ou ter feito o seguinte em um navegador da Web:

1. Bifurcado o repositório MicrosoftDocs/realidade misturada.
2. Editar o artigo em seu fork.
3. As imagens que você está referenciando em seu artigo foram carregadas na pasta "mixed-reality-docs/images" na bifurcação.
4. Criou uma solicitação de pull para mesclar a bifurcação no branch "mestre" do MicrosoftDocs/realidade misturada.

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

Visualizando seu trabalho

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

Observação

A visualização das alterações em etapas só está disponível para os funcionários da Microsoft

Funcionários da Microsoft: depois que suas contribuições tiverem sido mescladas no branch 'principal', você poderá examinar o conteúdo antes que ele fique público em /windows/mixed-reality?branch=main. Localize seu artigo usando o sumário na coluna à esquerda.

Editar no navegador versus editar com um cliente desktop

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

• Você não conta com 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).
• Carregar imagens e fazer referência a elas pode ser um trabalho difícil.

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

Usar o Visual Studio Code

Pelos motivos listados acima, você pode preferir usar um cliente desktop para editar a documentação em vez de um navegador da Web. O uso do Visual Studio Code é recomendado.

Instalação

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

1. Em um navegador da Web:
   1. Instale o Git para PC.
   2. Instale o Visual Studio Code.
   3. Bifurque MicrosoftDocs/realidade misturada se você ainda não fez isso.
   4. No seu fork, selecione Clonar ou baixar e copie a URL.
2. Crie um clone local de seu fork no Visual Studio Code:
   1. No menu Exibir, selecione Paleta de Comandos.
   2. Digite "Git: Clone."
   3. Cole a URL que você copiou.
   4. Escolha onde salvar o clone em seu PC.
   5. Selecione Abrir repositório no pop-up.

Editar a documentaçã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 criação de artigos e os fundamentos de edição de Markdown descritos acima aplicam-se também ao usar o Visual Studio Code.

1. Certifique-se de que seu fork clonado esteja 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 MicrosoftDocs/mixed-reality 'master' para seu fork (verifique se a seta está apontando para o caminho certo).

      

   2. No Visual Studio Code, selecione o botão sincronizar para sincronizar seu fork recém-atualizado para o clone local.

      

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. Salve as alterações no Explorer.

      

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

      

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

      

3. Em um navegador da Web, crie uma solicitação de pull para sincronizar novas alterações em seu fork de volta para MicrosoftDocs/mixed-reality 'master' (verifique se a seta está apontando da maneira correta).

   

Extensões úteis

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

• Extensão de redução de documentos para Visual Studio Code – use Alt + M para abrir um menu de opções de criação de documentos como este:
  • Pesquisar e fazer referência a imagens que você carregou.
  • Adicione formatação como listas, tabelas e balões específicos a documentos 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.