Diretrizes de documentação – MRTK2

  • Artigo
MRTK

Este documento descreve as diretrizes e os padrões de documentação do MRTK (Kit de Ferramentas do Realidade Misturada). Isso fornece uma introdução aos aspectos técnicos da escrita e geração de documentação, para realçar armadilhas comuns e descrever o estilo de escrita recomendado.

A própria página deve servir como exemplo, portanto, usa o estilo pretendido e os recursos de marcação mais comuns da documentação.

Funcionalidade e marcação

Esta seção descreve os recursos necessários com frequência. Para ver como eles funcionam, examine o código-fonte da página.

  1. Listas numeradas
    1. Listas numeradas aninhadas com pelo menos 3 espaços em branco à esquerda
    2. O número real no código é irrelevante; A análise cuidará da definição do número de item correto.
  • Listas de marcadores
    • Listas de marcadores aninhados
  • Texto em negrito com **asterisco duplo**
  • texto itálico com _underline_ ou *asterisco único*
  • Texto highlighted as code dentro de uma frase 'usando backquotes'
  • Links para páginas de documentos Diretrizes de documentação do MRTK
  • Links para âncoras em uma página; as âncoras são formadas substituindo espaços por traços e convertendo em minúsculas

Para exemplos de código, usamos os blocos com três backticks ''' e especificamos csharp como o idioma para realce de sintaxe:

int SampleFunction(int i)
{
   return i + 42;
}

Ao mencionar código dentro de uma frase use a single backtick.

TODOs

Evite usar TODOs em documentos, pois ao longo do tempo esses TODOs (como TODOs de código) tendem a se acumular e informações sobre como eles devem ser atualizados e por que são perdidos.

Se for absolutamente necessário adicionar um TODO, siga estas etapas:

  1. Registre um novo problema no Github descrevendo o contexto por trás do TODO e forneça informações suficientes para que outra contribuidor possa entender e, em seguida, abordar o TODO.
  2. Referencie a URL do problema no todo nos documentos.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: uma breve desfoque sobre o problema -->

Seções realçadas

Para realçar pontos específicos para o leitor, use > [! OBSERVAÇÃO] , > [! AVISO] , e > [! IMPORTANTE] para produzir os estilos a seguir. É recomendável usar anotações para pontos gerais e pontos de aviso/importantes apenas para casos relevantes especiais.

Observação

Exemplo de uma anotação

Aviso

Exemplo de um aviso

Importante

Exemplo de um comentário importante

Layout de página

Introdução

A parte logo após o título do capítulo main deve servir como uma breve introdução do que se trata o capítulo. Não torne isso muito longo, em vez disso, adicione sub-títulos. Eles permitem vincular a seções e podem ser salvos como indicadores.

Corpo principal

Use títulos de dois e três níveis para estruturar o restante.

Minissões

Use uma linha de texto em negrito para blocos que devem se destacar. Podemos substituir isso por manchetes de quatro níveis em algum momento.

Seção 'Veja também'

A maioria das páginas deve terminar com um capítulo chamado Ver também. Este capítulo é simplesmente uma lista com marcadores de links para páginas relacionadas a este tópico. Esses links também podem aparecer no texto da página quando apropriado, mas isso não é necessário. Da mesma forma, o texto da página pode conter links para páginas que não estão relacionadas ao tópico main, elas não devem ser incluídas na lista Ver também. Confira o capítulo ''Veja também'' desta página como um exemplo para a escolha de links.

Sumário (TOC)

Os arquivos toc são usados para gerar as barras de navegação na documentação de github.io do MRTK. Sempre que um novo arquivo de documentação for adicionado, verifique se há uma entrada para esse arquivo em um dos arquivos toc.yml da pasta de documentação. Somente os artigos listados nos arquivos toc aparecerão na navegação dos documentos do desenvolvedor. Pode haver um arquivo toc para cada subpasta na pasta de documentação que pode ser vinculada a qualquer arquivo toc existente para adicioná-lo como uma subseção à parte correspondente da navegação.

Estilo

Estilo de escrita

Regra geral: tente soar profissional. Isso geralmente significa evitar um "tom de conversa". Tente também evitar hipérbole e sensacionalismo.

  1. Não tente ser (excessivamente) engraçado.
  2. Nunca escreva 'I'
  3. Evite "nós". Isso geralmente pode ser reformulado facilmente, usando 'MRTK'. Exemplo: "damos suporte a esse recurso" –> "O MRTK dá suporte a esse recurso" ou "há suporte para os seguintes recursos ...".
  4. Da mesma forma, tente evitar "você". Exemplo: "Com essa simples alteração, seu sombreador se torna configurável!" –> "Os sombreadores podem ser configuráveis com pouco esforço".
  5. Não use "frases desleixadas".
  6. Evite soar muito animado, não precisamos vender nada.
  7. Da mesma forma, evite ser excessivamente dramático. Pontos de exclamação raramente são necessários.

Uso de maiúsculas

  • Use Maiúsculas e Minúsculas para títulos. Ie. colocar em maiúscula a primeira letra e os nomes, mas nada mais.
  • Use inglês normal para todo o resto. Isso significa que não coloque palavras arbitrárias em maiúsculas, mesmo que elas detêm um significado especial nesse contexto. Prefira texto itálico para realçar determinadas palavras, veja abaixo.
  • Quando um link é inserido em uma frase (que é o método preferencial), o nome do capítulo padrão sempre usa letras maiúsculas, quebrando a regra de nenhuma maiúscula arbitrária dentro do texto. Portanto, use um nome de link personalizado para corrigir a capitalização. Por exemplo, aqui está um link para a documentação de controle de limites .
  • Use nomes em maiúsculas, como Unity.
  • NÃO coloque o "editor" em maiúscula ao escrever o editor do Unity.

Ênfase e realce

Há duas maneiras de enfatizar ou realçar palavras, tornando-as ousadas ou tornando-as itálicas. O efeito do texto em negrito é que o texto em negrito se destaca e, portanto, pode ser facilmente notado ao deslizar um pedaço de texto ou até mesmo apenas rolar sobre uma página. Negrito é ótimo para destacar frases que as pessoas devem lembrar. No entanto, use texto em negrito raramente, pois geralmente está distraindo.

Muitas vezes, desejamos "agrupar" algo que pertença logicamente juntos ou realçar um termo específico, pois ele tem um significado especial. Essas coisas não precisam se destacar do texto geral. Use texto em itálico como um método leve para realçar algo.

Da mesma forma, quando um nome de arquivo, um caminho ou uma entrada de menu é mencionado no texto, prefira torná-lo itálico para agrupá-lo logicamente, sem distrair.

Em geral, tente evitar realces de texto desnecessários. Os termos especiais podem ser realçados uma vez para tornar o leitor ciente, não repita esse realce em todo o texto, quando ele não serve mais para nada e apenas distrai.

Mencionando entradas de menu

Ao mencionar uma entrada de menu em que um usuário deve clicar, a convenção atual é: Arquivos > de Projeto > Criar > Folha

Insira o máximo possível de links úteis para outras páginas, mas cada link apenas uma vez. Suponha que um leitor clique em cada link da página e pense no quão irritante seria, se a mesma página abrir 20 vezes.

Prefira links inseridos em uma frase:

Evite links externos, eles podem ficar desatualizados ou conter conteúdo protegido por direitos autorais.

Ao adicionar um link, considere se ele também deve ser listado na seção Ver também . Da mesma forma, marcar se um link para a nova página deve ser adicionado à página vinculada.

Imagens/capturas de tela

Use capturas de tela com moderação. Manter imagens na documentação é muito trabalho, pequenas alterações na interface do usuário podem tornar muitas capturas de tela desatualizadas. As seguintes regras reduzirão o esforço de manutenção:

  1. Não use capturas de tela para itens que podem ser descritos em texto. Especialmente, nunca captura de tela de uma grade de propriedades com a única finalidade de mostrar nomes e valores de propriedade.
  2. Não inclua itens em uma captura de tela que sejam irrelevantes para o que é mostrado. Por exemplo, quando um efeito de renderização é mostrado, faça uma captura de tela do visor, mas exclua qualquer interface do usuário ao seu redor. Mostrando alguma interface do usuário, tente mover janelas de modo que apenas essa parte importante esteja na imagem.
  3. Ao incluir a interface do usuário de captura de tela, mostre apenas as partes importantes. Por exemplo, ao falar sobre botões em uma barra de ferramentas, crie uma imagem pequena que mostre os botões importantes da barra de ferramentas, mas exclua tudo ao seu redor.
  4. Use apenas imagens fáceis de reproduzir. Isso significa que não pinte marcadores nem realces em capturas de tela. Primeiro, não há regras consistentes como elas devem parecer, de qualquer maneira. Em segundo lugar, reproduzir essa captura de tela é um esforço adicional. Em vez disso, descreva as partes importantes no texto. Há exceções a essa regra, mas elas são raras.
  5. Obviamente, é muito mais esforço recriar um GIF animado. Espere ser responsável por recriá-lo até o fim dos tempos, ou esperar que as pessoas joguem fora, se não quiserem passar esse tempo.
  6. Mantenha o número de imagens em um artigo baixo. Geralmente, um bom método é fazer uma captura de tela geral de alguma ferramenta, que mostra tudo e, em seguida, descrever o restante no texto. Isso facilita a substituição da captura de tela quando necessário.

Alguns outros aspectos:

  • A interface do usuário do editor para capturas de tela deve usar o editor de tema cinza claro, pois nem todos os usuários têm acesso ao tema escuro e gostaríamos de manter as coisas o mais consistentes possível.
  • A largura da imagem padrão é de 500 pixels, pois ela é exibida bem na maioria dos monitores. Tente não se desviar muito dele. A largura de 800 pixels deve ser a máxima.
  • Use PNGs para capturas de tela da interface do usuário.
  • Use PNGs ou JPGs para capturas de tela do visor 3D. Prefira qualidade em relação à taxa de compactação.

Lista de propriedades do componente

Ao documentar uma lista de propriedades, use texto em negrito para realçar o nome da propriedade e, em seguida, quebras de linha e texto regular para descrevê-las. Não use sub capítulos ou listas de marcadores.

Além disso, não se esqueça de terminar todas as frases com um ponto final.

Lista de verificação de conclusão de página

  1. Verifique se as diretrizes deste documento foram seguidas.
  2. Navegue pela estrutura do documento e veja se o novo documento pode ser mencionado na seção Ver também de outras páginas.
  3. Se disponível, tenha alguém com conhecimento do tópico que revise a página para correção técnica.
  4. Peça a alguém que leia a página para estilo e formatação. Isso pode ser alguém que não está familiarizado com o tópico, o que também é uma boa ideia para obter comentários sobre o quão compreensível é a documentação.

Documentação de origem

A documentação da API será gerada automaticamente dos arquivos de origem do MRTK. Para facilitar isso, os arquivos de origem são necessários para conter o seguinte:

Além do indicado acima, o código deve ser bem comentado para permitir manutenção, correções de bugs e facilidade de personalização.

Blocos de resumo de classe, struct e enum

Se uma classe, struct ou enumeração estiver sendo adicionada ao MRTK, sua finalidade deverá ser descrita. Isso é para assumir a forma de um bloco de resumo acima da classe .

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

Se houver dependências de nível de classe, elas deverão ser documentadas em um bloco de comentários, imediatamente abaixo do resumo.

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

As solicitações de pull enviadas sem resumos para classes, estruturas ou enumerações não serão aprovadas.

Blocos de resumo de eventos, método, propriedade

Propriedades, métodos e eventos (PMEs), bem como campos, devem ser documentados com blocos de resumo, independentemente da visibilidade do código (pública, privada, protegida e interna). A ferramenta de geração de documentação é responsável por filtrar e publicar apenas os recursos públicos e protegidos.

OBSERVAÇÃO: um bloco de resumo não é necessário para métodos do Unity (por exemplo: Awake, Start, Update).

A documentação do PME é necessária para que uma solicitação de pull seja aprovada.

Como parte de um bloco de resumo do PME, o significado e a finalidade dos parâmetros e dos dados retornados são necessários.

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

Versão e dependências de introdução de recursos

Como parte da documentação de resumo da API, informações sobre a versão do MRTK na qual o recurso foi introduzido e quaisquer dependências devem ser documentadas em um bloco de comentários.

As dependências devem incluir dependências de extensão e/ou plataforma.

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

Campos serializados

É uma boa prática usar o atributo de dica de ferramenta do Unity para fornecer documentação de runtime para os campos de um script no inspetor.

Para que as opções de configuração sejam incluídas na documentação da API, os scripts são necessários para incluir pelo menos o conteúdo da dica de ferramenta em um bloco de resumo.

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

Valores de enumeração

Ao definir e enumerar, o código também deve documentar o significado dos valores de enumeração usando um bloco de resumo. Opcionalmente, os blocos de comentários podem ser usados para fornecer detalhes adicionais para aprimorar a compreensão.

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

Documentação de instruções

Muitos usuários do Realidade Misturada Toolkit talvez não precisem usar a documentação da API. Esses usuários aproveitarão nossos pré-fabricados e scripts pré-fabricados e reutilizáveis para criar suas experiências.

Cada área de recurso conterá um ou mais arquivos markdown (.md) que descrevem em um nível bastante alto, o que é fornecido. Dependendo do tamanho e/ou da complexidade de uma determinada área de recurso, pode haver a necessidade de arquivos adicionais, até um por recurso fornecido.

Quando um recurso é adicionado (ou o uso é alterado), a documentação de visão geral deve ser fornecida.

Como parte desta documentação, as seções de instruções, incluindo ilustrações, devem ser fornecidas para ajudar os clientes novos em um recurso ou conceito na introdução.

Documentação de design

Realidade Misturada oferece uma oportunidade de criar mundos totalmente novos. Parte disso provavelmente envolverá a criação de ativos personalizados para uso com o MRTK. Para tornar isso o mais atrito possível para os clientes, os componentes devem fornecer documentação de design que descreva qualquer formatação ou outros requisitos para ativos de arte.

Alguns exemplos em que a documentação de design pode ser útil:

  • Modelos de cursor
  • Visualizações de mapeamento espacial
  • Arquivos de efeito de som

Esse tipo de documentação é altamente recomendável e pode ser solicitado como parte de um revisão da solicitação de pull.

Isso pode ou não ser diferente da recomendação de design no site do Desenvolvedor do MS

Notas de desempenho

Alguns recursos importantes vêm a um custo de desempenho. Geralmente, esse código depende muito de como eles são configurados.

Por exemplo:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

As notas de desempenho são recomendadas para componentes pesados de CPU e/ou GPU e podem ser solicitadas como parte de um revisão da solicitação de pull. Todas as notas de desempenho aplicáveis devem ser incluídas na API e na documentação de visão geral.

Alterações de quebra

A documentação de alterações interruptivas consiste em um arquivo de nível superior que se vincula aos breaking-changes.md individuais de cada área de recurso.

A área de recurso breaking-changes.md arquivos deve conter a lista de todas as alterações interruptivas conhecidas para uma determinada versão, bem como o histórico de alterações interruptivas de versões anteriores.

Por exemplo:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

As informações contidas no nível do recurso breaking-changes.md arquivos serão agregadas às notas de versão para cada nova versão do MRTK.

Todas as alterações interruptivas que fazem parte de uma alteração devem ser documentadas como parte de uma solicitação de pull.

Ferramentas para editar MarkDown

Visual Studio Code é uma ótima ferramenta para editar arquivos markdown que fazem parte da documentação do MRTK.

Ao escrever a documentação, a instalação das duas extensões a seguir também é altamente recomendada:

  • Extensão Markdown do Docs para Visual Studio Code – use Alt+M para abrir um menu de opções de criação de documentos.

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

Ambos vêm empacotados no Pacote de Criação do Docs publicado pela Microsoft.

Confira também