Partilhar via

Contribuindo para a documentação do desenvolvedor de Realidade Mista

  • Artigo

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

Os documentos de Realidade Mista agora estão hospedados 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 no /windows/mixed-reality.

Esta página abrange as etapas básicas e diretrizes para contribuir e links para Markdown básicos. Obrigado pelo seu contributo!

Acordos de recompra disponíveis

Nome do repositório URL
Azure Remote Rendering MicrosoftDocs/azure-docs/articles/renderização remota
HoloLens MicrosoftDocs/HoloLens
Mixed Reality MicrosoftDocs/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 no 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 às 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.
  • Guarde os seus códigos de recuperação num local seguro.
  • Atualize as configurações do seu perfil público.
    • Defina seu nome e considere definir seu e-mail público como Não mostrar meu endereço de e-mail.
    • Recomendamos que carregue uma foto de perfil porque é apresentada uma miniatura nas páginas de documentos para as quais contribui.
  • Se você planeja usar a linha de comando, considere configurar o 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 em um artigo existente via GitHub em um navegador da Web:

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

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

    Editar um artigo.

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

  4. Atualizar metadados na parte superior de cada artigo:

    • title: 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.
    • author: 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 de @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: Auxílio de palavras-chave em 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 pull request para mesclar sua ramificação criada automaticamente em 'master'.

  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 à redirections matriz:

{
    "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. Certifique-se de que o caminho começa com mixed-reality-docs e termina com .md.
  • O redirect_url é o URL público relativo do artigo antigo para o novo artigo. Certifique-se de que este URL não contém mixed-reality-docs ou .md, 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 #section . 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. A predefinição é false. Use true se quiser preservar o valor do ms.documentid atributo 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 'master' do MicrosoftDocs/realidade mista (usando o botão Fork no canto superior direito).

    Criação de uma bifurcação.

  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 hífenes em vez de espaços e não use pontuação ou apóstrofos) e acrescente ".md"

    Atribua um nome à sua nova página.

    Importante

    Certifique-se de criar o novo artigo a partir 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 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 secção acima.

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

  7. Adicione uma ## See also seção 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 'master' da bifurcação no MicrosoftDocs/mixed-reality 'master' (verifique se a seta está apontando para o caminho correto).

    Crie pull request a partir da sua bifurcação para o MicrosoftDocs/mixed-reality

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 à maneira como as tabelas de estilos da documentação técnica da Microsoft, 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.

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

Adicionar imagens

Você precisará carregar suas imagens para a pasta "mixed-reality-docs/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/mixed-reality.
  2. Editou o artigo na sua bifurcação.
  3. Carregue as imagens que você está referenciando em seu artigo para a pasta "mixed-reality-docs/images" em sua bifurcação.
  4. Criou uma solicitação pull para mesclar sua bifurcação na ramificação 'master' do MicrosoftDocs/mixed-reality.

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 através de um navegador da web, você pode selecionar a guia Visualizar perto da parte superior da página para visualizar seu trabalho antes de confirmar.

Nota

A pré-visualização das alterações faseadas só está disponível para funcionários da Microsoft

Funcionários da Microsoft: uma vez que suas contribuições tenham sido mescladas na ramificação 'principal', você pode revisar o conteúdo antes que ele se torne público em /windows/mixed-reality?branch=main. Encontre seu artigo usando o sumário 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 o Visual Studio Code com algumas extensões úteis ao contribuir.

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

Configurar

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

  1. Em um navegador da Web:
    1. Instale o Git para o seu PC.
    2. Instalar o Visual Studio Code.
    3. Fork MicrosoftDocs/mixed-reality se ainda não o fez.
    4. Na bifurcação, selecione Clonar 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 Abrir repositório 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 editar e criar artigos, e as noções básicas de edição Markdown, de cima também se aplicam ao usar o Visual Studio Code.

  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 no MicrosoftDocs/mixed-reality 'master' com sua bifurcação (verifique se a seta está apontando para o caminho certo).

      Sincronize alterações do MicrosoftDocs/realidade mista com 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. Salve as alterações no Explorer.

      Escolha

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

      Escolha

    4. Selecione o botão de sincronização 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/mixed-reality 'master' (verifique se a seta está apontando para o caminho correto).

    Crie pull request a partir da sua bifurcação para o MicrosoftDocs/mixed-reality

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 abrir um menu de opções de criação de documentos como:
    • Pesquise e faça referência às imagens que carregou.
    • Adicione formatação como listas, tabelas e textos explicativos específicos de documentos 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 mouse em uma palavra com erros ortográficos para alterá-la ou salvá-la no dicionário.