Compartilhar via

Diretrizes de documentação — MRTK2

  • Artigo
MRTK

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

A página em si deve servir de 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, observe 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 se encarregará de definir o número do item correto.
  • Listas de marcadores
    • Listas de marcadores aninhadas
  • Texto em negrito com **asterisco duplo**
  • texto em itálico com _sublinhado_ ou *asterisco único*
  • Texto highlighted as code dentro de uma frase 'usando aspas invertidas'
  • Links para páginas de documentos, diretrizes de documentação do MRTK
  • Links para âncoras dentro de uma página; as âncoras são formadas substituindo espaços por traços e convertendo para minúsculas

Para exemplos de código, usamos os blocos com três acentos graves ''' e especificamos csharp como a linguagem para realce de sintaxe:

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

Ao mencionar o 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 se perdem.

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 seja capaz de entender e, em seguida, abordar o TODO.
  2. Faça referência à URL do problema no processo nos documentos.

<-- TODO:https://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE Uma breve sinopse sobre o assunto ->

Seções destacadas

Para destacar pontos específicos para o leitor, use > [! NOTA] , > [! AVISO] e > [! IMPORTANTE] para produzir os seguintes estilos. Recomenda-se o uso de notas para pontos gerais e pontos de advertência/importância apenas para casos especiais relevantes.

Observação

Exemplo de uma nota

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 principal deve servir como uma breve introdução sobre o que é o capítulo. Não torne isso muito longo, em vez disso, adicione subtítulos. Eles permitem vincular a seções e podem ser salvos como marcadores.

Corpo principal

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

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.

Secção «Ver 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 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 é obrigató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, estes não devem ser incluídos na lista Ver também . Veja o capítulo ''Ver também'' desta página como um exemplo para a escolha de links.

Índice (TOC)

Os arquivos de sumário são usados para gerar as barras de navegação na documentação do MRTK github.io. 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 vinculado 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érboles e sensacionalismo.

  1. Não tente ser (excessivamente) engraçado.
  2. Nunca escreva 'eu'
  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 "os recursos a seguir têm suporte ...".
  4. Da mesma forma, tente evitar 'você'. Exemplo: "Com essa simples mudança, seu sombreador se torna configurável!" -> "Os sombreadores podem ser configurados com pouco esforço."
  5. Não use 'frases desleixadas'.
  6. Evite parecer excessivamente 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 manchetes. Ie. Coloque a primeira letra e os nomes em maiúscula, mas nada mais.
  • Use o inglês regular para todo o resto. Isso significa que não coloque palavras arbitrárias em maiúsculas, mesmo que tenham um significado especial nesse contexto. Prefira texto em itálico para destacar certas palavras, veja abaixo.
  • Quando um link é incorporado em uma frase (que é o método preferido), o nome do capítulo padrão sempre usa letras maiúsculas, quebrando assim a regra de não usar maiúsculas arbitrárias dentro do texto. Portanto, use um nome de link personalizado para corrigir a capitalização. Como exemplo, aqui está um link para a documentação de controle de limites.
  • Coloque nomes em maiúsculas, como Unity.
  • NÃO coloque "editor" em maiúsculas ao escrever o editor do Unity.

Ênfase e destaque

Existem duas maneiras de enfatizar ou destacar palavras, tornando-as em negrito ou em itálico. O efeito do texto em negrito é que o texto em negrito se destaca e, portanto, pode ser facilmente notado ao folhear um pedaço de texto ou até mesmo rolar uma página. Negrito é ótimo para destacar frases que as pessoas devem lembrar. No entanto, use texto em negrito raramente, porque geralmente é uma distração.

Muitas vezes, deseja-se "agrupar" algo que pertence logicamente ou destacar um termo específico, porque tem um significado especial. Essas coisas não precisam ficar de fora do texto geral. Use texto em itálico como um método leve para destacar algo.

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

Em geral, tente evitar realces de texto desnecessários. Termos especiais podem ser destacados uma vez para conscientizar o leitor, não repita esse destaque ao longo do texto, quando não serve mais para nada e apenas distrai.

Mencionando entradas de menu

Ao mencionar uma entrada de menu na qual um usuário deve clicar, a convenção atual é: Arquivos > de projeto > Criar > folha

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 todos os links da página e pense em como seria irritante se a mesma página abrisse 20 vezes.

Prefira links incorporados 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 Consulte 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 dá 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 coisas que podem ser descritas em texto. Especialmente, nunca faça uma captura de tela de uma grade de propriedades com o único propósito de mostrar nomes e valores de propriedades.
  2. Não inclua coisas 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 da janela de visualização, mas exclua qualquer interface do usuário em torno dela. Mostrando alguma interface do usuário, tente mover as janelas de forma 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, crie uma pequena imagem 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 ou destaques em capturas de tela. Primeiro, não há regras consistentes sobre como isso deve 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. Existem exceções a esta regra, mas 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 espere que as pessoas o joguem fora, se não quiserem gastar 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 depois descrever o resto 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 padrão da imagem é de 500 pixels, pois isso é exibido bem na maioria dos monitores. Tente não se desviar muito disso. 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 da janela de visualização 3D. Prefira qualidade à taxa de compressã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 normal para descrevê-las. Não use subcapítulos ou listas de marcadores.

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

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

  1. Certifique-se de que as diretrizes deste documento foram seguidas.
  2. Navegue pela estrutura do documento e veja se o novo documento pode ser mencionado na seção Consulte também de outras páginas.
  3. Se disponível, peça a alguém com conhecimento do tópico que revise a página quanto à correção técnica.
  4. Peça a alguém que revise a página quanto ao estilo e formatação. Pode ser alguém não familiarizado com o tópico, o que também é uma boa ideia para obter feedback sobre a compreensão da documentação.

Documentação de origem

A documentação da API será gerada automaticamente a partir dos arquivos de origem do MRTK. Para facilitar isso, os arquivos de origem devem 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, enumeração

Se uma classe, struct ou enumeração estiver sendo adicionada ao MRTK, sua finalidade deverá ser descrita. Isso deve 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>

Pull Requests enviados sem resumos para classes, estruturas ou enumerações não serão aprovados.

Propriedade, método, blocos de resumo de eventos

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

NOTA: Um bloco de resumo não é necessário para métodos do Unity (por exemplo: Despertar, 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 PME, o significado e a finalidade dos parâmetros e 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, as 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 tooltip 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 devem 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 melhorar 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 podem não precisar usar a documentação da API. Esses usuários aproveitarão nossos pré-fabricados e scripts 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 complexidade de uma determinada área de recursos, 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, seções de instruções, incluindo ilustrações, devem ser fornecidas para ajudar os clientes novos em um recurso ou conceito a começar.

Documentação de design

A Realidade Mista 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 de atrito possível para os clientes, os componentes devem fornecer documentação de design descrevendo 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 efeitos sonoros

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 do MS Developer

Observações sobre desempenho

Alguns recursos importantes têm um custo de desempenho. Muitas vezes, esse código dependerá muito de como eles estã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 API e na documentação de visão geral.

Alterações da falha

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

A área de recursos breaking-changes.md arquivos deve conter a lista de todas as alterações significativas conhecidas para uma determinada versão , bem como o histórico de alterações significativas 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 nos arquivos breaking-changes.md nível de recurso serão agregadas às notas de versão de cada nova versão do MRTK.

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

Ferramentas para editar MarkDown

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

Confira também