Directrices de documentación: MRTK2

  • Artículo
MRTK

En este documento se describen las directrices de documentación y los estándares para Mixed Reality Toolkit (MRTK). Esto proporciona una introducción a los aspectos técnicos de la escritura y generación de documentación, para resaltar los problemas comunes y para describir el estilo de escritura recomendado.

Se supone que la propia página sirve como ejemplo, por lo que usa el estilo previsto y las características de marcado más comunes de la documentación.

Funcionalidad y marcado

En esta sección se describen las características necesarias con frecuencia. Para ver cómo funcionan, examine el código fuente de la página.

  1. Listas numeradas
    1. Listas numeradas anidadas con al menos 3 espacios en blanco iniciales
    2. El número real en el código es irrelevante; El análisis se encargará de establecer el número de elemento correcto.
  • Listas de puntos de viñetas
    • Listas de puntos de viñetas anidadas
  • Texto en negrita con **asterisco doble**
  • textoen cursiva con _subrayado_ o *asterisco único*
  • Texto highlighted as code dentro de una frase "usando comillas inversas"
  • Vínculos a las páginas de documentos directrices de documentación de MRTK
  • Vínculos a delimitadores dentro de una página; los anclajes se forman reemplazando los espacios por guiones y convirtiéndose en minúsculas.

En el caso de los ejemplos de código, usamos los bloques con tres acentos versos ''' y especificamos csharp como lenguaje para resaltar la sintaxis:

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

Al mencionar código dentro de una oración use a single backtick.

TODOs

Evite el uso de TODOs en documentos, ya que con el tiempo estos TODOs (como los TODOs de código) tienden a acumularse e información sobre cómo deben actualizarse y por qué se pierden.

Si es absolutamente necesario agregar un todo, siga estos pasos:

  1. Abra un nuevo problema en Github que describa el contexto detrás de todo y proporcione suficiente fondo para que otro colaborador pueda entender y, a continuación, solucionar el todo.
  2. Haga referencia a la dirección URL del problema en la lista de documentos.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: un breve desenfoque sobre el problema->

Secciones resaltadas

Para resaltar puntos específicos al lector, use > [! NOTA] , > [! ADVERTENCIA] , y > [! IMPORTANTE] para generar los estilos siguientes. Se recomienda usar notas para puntos generales y puntos de advertencia/puntos importantes solo para casos especiales pertinentes.

Nota

Ejemplo de una nota

Advertencia

Ejemplo de una advertencia

Importante

Ejemplo de un comentario importante

Diseño de página

Introducción

La parte justo después del título del capítulo principal debe servir como una breve introducción de lo que trata el capítulo. No haga que esto sea demasiado largo, en su lugar agregue subtítulos. Estos permiten vincular a secciones y se pueden guardar como marcadores.

Cuerpo principal

Use titulares de dos y tres niveles para estructurar el resto.

Mini secciones

Use una línea de texto en negrita para bloques que deben destacarse. Podríamos reemplazarlo por titulares de cuatro niveles en algún momento.

Sección "Ver también"

La mayoría de las páginas deben terminar con un capítulo llamado See también. Este capítulo es simplemente una lista con viñetas de vínculos a páginas relacionadas con este tema. Estos vínculos también pueden aparecer en el texto de la página cuando corresponda, pero esto no es necesario. Del mismo modo, el texto de la página puede contener vínculos a páginas que no están relacionadas con el tema principal, no deben incluirse en la lista Ver también . Vea el capítulo "Ver también" de esta página como ejemplo de la elección de vínculos.

Tabla de contenido (TOC)

Los archivos Toc se usan para generar las barras de navegación en la documentación de MRTK github.io. Cada vez que se agrega un nuevo archivo de documentación, asegúrese de que hay una entrada para ese archivo en uno de los archivos toc.yml de la carpeta de documentación. Solo los artículos enumerados en los archivos toc se mostrarán en la navegación de los documentos para desarrolladores. Puede haber un archivo toc para cada subcarpeta de la carpeta de documentación que se puede vincular a cualquier archivo toc existente para agregarlo como subsección a la parte correspondiente de la navegación.

Estilo

Estilo de escritura

Regla general general: trate de sonar profesional. Esto suele significar evitar un "tono conversacional". También trata de evitar hiperbole y sensacionalismo.

  1. No trates de ser (demasiado) gracioso.
  2. Nunca escriba 'I'
  3. Evite "nosotros". Normalmente, esto se puede volver a procesar fácilmente, con "MRTK" en su lugar. Ejemplo: "se admite esta característica":> "MRTK admite esta característica" o "se admiten las siguientes características...".
  4. Del mismo modo, intente evitar "usted". Ejemplo: "Con este simple cambio, el sombreador se puede configurar!":> "Los sombreadores se pueden configurar con poco esfuerzo".
  5. No use "frases descuidadas".
  6. Evite sonar demasiado excitado, no es necesario vender nada.
  7. De forma similar, evite ser demasiado dramático. Las marcas de exclamación rara vez son necesarias.

Uso de mayúsculas

  • Use el caso de frase para los titulares. Ie. escribe en mayúsculas la primera letra y los nombres, pero nada más.
  • Use inglés normal para todo lo demás. Esto significa que no capitalizan palabras arbitrarias, aunque contengan un significado especial en ese contexto. Prefiere texto cursiva para resaltar ciertas palabras, consulte a continuación.
  • Cuando un vínculo se inserta en una oración (que es el método preferido), el nombre del capítulo estándar siempre usa letras mayúsculas, lo que rompe la regla de ninguna mayúscula arbitraria dentro del texto. Por lo tanto, use un nombre de vínculo personalizado para corregir la mayúscula. Por ejemplo, este es un vínculo a la documentación del control enlazado .
  • Haga mayúsculas de nombres, como Unity.
  • No escriba mayúsculas "editor" al escribir el editor de Unity.

Énfasis y resaltado

Hay dos maneras de resaltar o resaltar palabras, haciéndolas negritas o cursiva. El efecto del texto en negrita es que el texto en negrita se pega y, por lo tanto, se puede observar fácilmente mientras se despeda un fragmento de texto o incluso simplemente se desplaza por una página. Negrita es excelente para resaltar frases que la gente debe recordar. Sin embargo, use texto en negrita rara vez, ya que generalmente se distrae.

A menudo, uno quiere "agrupar" algo que pertenece lógicamente o resaltar un término específico, ya que tiene un significado especial. Estas cosas no necesitan destacarse del texto general. Use texto en cursiva como método ligero para resaltar algo.

De forma similar, cuando se menciona un nombre de archivo, una ruta de acceso o una entrada de menú en el texto, prefiere que sea cursiva para agruparlo lógicamente, sin distraerse.

En general, intente evitar el resaltado de texto innecesario. Los términos especiales se pueden resaltar una vez para que el lector sea consciente, no repita este resaltado en todo el texto, cuando ya no tenga ningún propósito y solo distraiga.

Mencionar entradas de menú

Al mencionar una entrada de menú que un usuario debe hacer clic, la convención actual es: Crear hoja de archivos de > proyecto >>

Inserte tantos vínculos útiles a otras páginas como sea posible, pero cada vínculo solo una vez. Supongamos que un lector hace clic en cada vínculo de la página y piensa en lo molesto que sería, si la misma página se abre 20 veces.

Preferir vínculos incrustados en una oración:

Evite los vínculos externos, pueden quedar obsoletos o contener contenido protegido por derechos de autor.

Al agregar un vínculo, considere si también debe aparecer en la sección Ver también . Del mismo modo, compruebe si se debe agregar un vínculo a la nueva página a la página vinculada.

Imágenes y capturas de pantalla

Use capturas de pantalla con moderación. Mantener imágenes en la documentación es mucho trabajo, los pequeños cambios en la interfaz de usuario pueden hacer una gran cantidad de capturas de pantalla obsoletas. Las reglas siguientes reducirán el esfuerzo de mantenimiento:

  1. No use capturas de pantalla para las cosas que se pueden describir en el texto. Especialmente, nunca captura de pantalla de una cuadrícula de propiedades con el único propósito de mostrar los nombres y valores de propiedad.
  2. No incluya elementos en una captura de pantalla que sean irrelevantes para lo que se muestra. Por ejemplo, cuando se muestra un efecto de representación, realice una captura de pantalla de la ventanilla, pero excluya cualquier interfaz de usuario que lo rodea. Mostrando alguna interfaz de usuario, intente mover ventanas para que solo esa parte importante esté en la imagen.
  3. Al incluir la interfaz de usuario de captura de pantalla, solo se muestran los elementos importantes. Por ejemplo, cuando se habla de botones de una barra de herramientas, cree una imagen pequeña que muestre los botones importantes de la barra de herramientas, pero excluya todo lo que lo rodea.
  4. Use solo imágenes que sean fáciles de reproducir. Esto significa que no pinta marcadores ni resaltados en capturas de pantalla. En primer lugar, no hay reglas coherentes de cómo deben ser estas. En segundo lugar, reproducir este tipo de captura de pantalla es un esfuerzo adicional. En su lugar, describa las partes importantes del texto. Hay excepciones a esta regla, pero son poco frecuentes.
  5. Obviamente, es mucho más esfuerzo volver a crear un GIF animado. Espere ser responsable de volver a crearlo hasta el final del tiempo, o espere que la gente lo desenlate, si no quieren dedicar ese tiempo.
  6. Mantenga el número de imágenes en un artículo bajo. A menudo, un buen método es hacer una captura de pantalla general de alguna herramienta, que muestra todo y, a continuación, describir el resto en texto. Esto facilita la sustitución de la captura de pantalla cuando sea necesario.

Otros aspectos:

  • La interfaz de usuario del editor para las capturas de pantalla debe usar el editor de temas gris claro, ya que no todos los usuarios tienen acceso al tema oscuro y nos gustaría mantener las cosas lo más coherentes posible.
  • El ancho de imagen predeterminado es de 500 píxeles, ya que se muestra bien en la mayoría de los monitores. Intente no desviarse demasiado de él. El ancho de 800 píxeles debe ser el máximo.
  • Use los grupos de seguridad de red para las capturas de pantalla de la interfaz de usuario.
  • Use PNG o JPG para capturas de pantalla de ventanilla 3D. Preferir la calidad sobre la relación de compresión.

Lista de propiedades de componente

Al documentar una lista de propiedades, use texto en negrita para resaltar el nombre de la propiedad y, a continuación, saltos de línea y texto normal para describirlas. No use sub capítulos ni listas de puntos de viñetas.

Además, no olvide finalizar todas las oraciones con un punto.

Lista de comprobación de finalización de página

  1. Asegúrese de que se han seguido las directrices de este documento.
  2. Examine la estructura del documento y compruebe si el nuevo documento podría mencionarse en la sección Ver también de otras páginas.
  3. Si está disponible, pida a alguien que conozca el tema a prueba de leer la página para obtener la corrección técnica.
  4. Pida a alguien que lea la página para el estilo y el formato. Puede ser alguien que no esté familiarizado con el tema, que también es una buena idea para obtener comentarios sobre lo comprensible que es la documentación.

Documentación de origen

La documentación de la API se generará automáticamente a partir de los archivos de origen de MRTK. Para facilitar esto, es necesario que los archivos de origen contengan lo siguiente:

Además de lo anterior, el código debe estar bien comentado para permitir el mantenimiento, las correcciones de errores y la facilidad de personalización.

Bloques de resumen de enumeración, struct y clase

Si se agrega una clase, estructura o enumeración a MRTK, se debe describir su propósito. Esto es para adoptar la forma de un bloque de resumen por encima de la clase .

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

Si hay dependencias de nivel de clase, deben documentarse en un bloque de comentarios, inmediatamente debajo del resumen.

/// <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>

Las solicitudes de incorporación de cambios enviadas sin resúmenes para clases, estructuras o enumeraciones no se aprobarán.

Bloques de propiedades, métodos y resumen de eventos

Las propiedades, los métodos y los eventos (PME), así como los campos se documentarán con bloques de resumen, independientemente de la visibilidad del código (pública, privada, protegida e interna). La herramienta de generación de documentación es responsable de filtrar y publicar solo las características públicas y protegidas.

NOTA: No se requiere un bloque de resumen para los métodos de Unity (por ejemplo: Despierto, Inicio, Actualización).

La documentación de PME es necesaria para que se apruebe una solicitud de incorporación de cambios.

Como parte de un bloque de resumen PME, se requiere el significado y el propósito de los parámetros y los datos devueltos.

/// <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>

Versión y dependencias de introducción de características

Como parte de la documentación de resumen de la API, la información sobre la versión de MRTK en la que se introdujo la característica y las dependencias deben documentarse en un bloque de comentarios.

Las dependencias deben incluir las dependencias de extensión o 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

Se recomienda usar el atributo de información sobre herramientas de Unity para proporcionar documentación en tiempo de ejecución para los campos de un script en el inspector.

Para que las opciones de configuración se incluyan en la documentación de la API, se requieren scripts para incluir al menos el contenido de la información sobre herramientas en un bloque de resumen.

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

Valores de enumeración

Al definir y enumerar, el código también debe documentar el significado de los valores de enumeración mediante un bloque de resumen. Los bloques de comentarios se pueden usar opcionalmente para proporcionar detalles adicionales para mejorar la comprensión.

/// <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>

Documentación de procedimientos

Es posible que muchos usuarios de Mixed Reality Toolkit no necesiten usar la documentación de la API. Estos usuarios aprovecharán nuestros objetos prefabricados, reutilizables y scripts para crear sus experiencias.

Cada área de características contendrá uno o varios archivos markdown (.md) que describen en un nivel bastante alto, lo que se proporciona. Según el tamaño o la complejidad de un área de características determinada, puede haber una necesidad de archivos adicionales, hasta una por característica proporcionada.

Cuando se agrega una característica (o se cambia el uso), se debe proporcionar documentación de información general.

Como parte de esta documentación, se deben proporcionar secciones de procedimientos, incluidas ilustraciones, para ayudar a los clientes a empezar a trabajar con una característica o concepto.

Documentación de diseño

Mixed Reality ofrece la oportunidad de crear mundos completamente nuevos. Parte de esto es probable que implique la creación de recursos personalizados para su uso con MRTK. Para que esto sea lo más fácil posible para los clientes, los componentes deben proporcionar documentación de diseño que describa cualquier formato u otros requisitos para los recursos de arte.

Algunos ejemplos en los que la documentación de diseño puede resultar útil:

  • Modelos de cursor
  • Visualizaciones de asignación espacial
  • Archivos de efectos de sonido

Este tipo de documentación es muy recomendable y se puede solicitar como parte de una revisión de solicitudes de incorporación de cambios.

Esto puede o no ser diferente de la recomendación de diseño en el sitio de MS Developer

Notas de rendimiento

Algunas características importantes tienen un costo de rendimiento. A menudo, este código dependerá mucho de cómo se configuren.

Por ejemplo:

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.

Las notas de rendimiento se recomiendan para los componentes pesados de CPU o GPU y se pueden solicitar como parte de una revisión de la solicitud de incorporación de cambios. Todas las notas de rendimiento aplicables se incluirán en la documentación de la API y la información general.

Últimos cambios

La documentación de cambios importantes consiste en un archivo de nivel superior que vincula a la breaking-changes.md individual de cada área de características.

El área de características breaking-changes.md archivos contiene la lista de todos los cambios importantes conocidos de una versión determinada , así como el historial de cambios importantes de las versiones anteriores.

Por ejemplo:

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

La información contenida en el nivel de característica breaking-changes.md archivos se agregará a las notas de la versión de cada nueva versión de MRTK.

Los cambios importantes que formen parte de un cambio deben documentarse como parte de una solicitud de incorporación de cambios.

Herramientas para editar MarkDown

Visual Studio Code es una excelente herramienta para editar archivos markdown que forman parte de la documentación de MRTK.

Al escribir documentación, también se recomienda instalar las dos extensiones siguientes:

  • Extensión markdown de Docs para Visual Studio Code: use Alt+M para abrir un menú de opciones de creación de documentos.

  • Corrector ortográfico de código: las palabras mal escritas estarán subrayadas. Haga clic con el botón derecho en una palabra mal escrita para cambiarla o guardarla en el diccionario.

Ambos vienen empaquetados en el paquete de creación de Docs publicado por Microsoft.

Consulte también