Diretrizes de documentação — MRTK2

MRTK

Este documento descreve as diretrizes e os padrões de documentação para Realidade Misturada Toolkit (MRTK). Isso fornece uma introdução aos aspectos técnicos de escrita e geração de documentação, para destacar 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 configuração do número de item correto.
  • Listas de pontos de marcador
    • Listas de pontos de marcador aninhados
  • Texto em negrito com **asterisco duplo**
  • textoitálico com _underline_ ou *single asterisk*
  • Texto highlighted as code dentro de uma frase 'usando backquotes'
  • Links para as diretrizes de documentação do MRTK de páginas de documentos
  • Links para âncoras em uma página; as âncoras são formadas pela substituição de espaços por traços e pela conversão 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 com o 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 outro colaborador possa entender e, em seguida, abordar o TODO.
  2. Faça referência à URL de problema no todo nos documentos.

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: uma breve sinopse 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 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 principal 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-manchetes. Elas permitem vincular-se a seções e podem ser salvas como indicadores.

Corpo principal

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

Mini seçõ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 de links apontados para marcadores 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 principal, elas não devem ser incluídas na lista Ver também . Confira o capítulo ''Ver também'' desta página como um exemplo para a escolha dos links.

TOC (Sumário)

Os arquivos toc são usados para gerar as barras de navegação na documentação do github.io 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 parecer 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' em vez disso. 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 alteração simples, seu sombreador se torna configurável!" -> "Sombreadores podem ser configurados 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 o caso Sentence para manchetes. Ie. maiúsculas da primeira letra e nomes, mas nada mais.
  • Use inglês normal para todo o resto. Isso significa que não capitalize palavras arbitrárias, mesmo que elas detenham um significado especial nesse contexto. Prefira texto itálico para realçar determinadas palavras, confira 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 assim a regra de nenhuma capitalização 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 maiúsculas, como Unity.
  • NÃO capitalize "editor" 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, porque geralmente está distraindo.

Muitas vezes, desejamos "agrupar" algo que pertence logicamente ou realçar um termo específico, porque ele tem um significado especial. Essas coisas não precisam se destacar do texto geral. Use o texto 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 se distrair.

Em geral, tente evitar realces desnecessários de texto. 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 nenhum propósito e só distrai.

Mencionando entradas de menu

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

Insira o maior número 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 em como seria irritante se a mesma página fosse aberta 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 Veja também . Da mesma forma, verifique 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 no 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 da captura de tela, mostre apenas as partes importantes. Por exemplo, ao falar sobre botões em uma barra de ferramentas, faça 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 não pintar marcadores ou realces em capturas de tela. Primeiro, não há regras consistentes como elas devem ser, 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. Muitas vezes, 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 desviar muito dele. A largura de 800 pixels deve ser o máximo.
  • Use PNGs para capturas de tela da interface do usuário.
  • Use PNGs ou JPGs para capturas de tela do visor 3D. Prefira a qualidade em vez da 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 subconjuntos ou listas de pontos de marcador.

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

Lista de verificação de conclusão da 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 da prova de tópicos que leia 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 não estar 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 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) e 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 somente os recursos públicos e protegidos.

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

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 da introdução do recurso

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. Os blocos de comentários podem ser usados opcionalmente 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 livre possível de atrito para os clientes, os componentes devem fornecer a 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 recomendado e pode ser solicitado como parte de uma revisão de solicitação de pull.

Isso pode ou não ser diferente da recomendação de design no site de 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 uma revisão de solicitação de pull. Todas as notas de desempenho aplicáveis devem ser incluídas na documentação de API e visão geral.

Alterações de quebra

A documentação de alterações interruptivas consiste em um arquivo de nível superior que é vinculado ao breaking-changes.md individual de cada área de recurso.

A área de recursos breaking-changes.md arquivos devem conter a lista de todas as alterações de falha conhecidas para uma determinada versão, bem como o histórico de alterações significativas de versões passadas.

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 criar 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 de Documentos publicado pela Microsoft.

Confira também