El contenido de referencia se consulta para obtener información específica. Es información que puede comprobar rápidamente, lo que significa que hay menos énfasis en frases y párrafos.
La referencia incluye información que puede representarse mejor en tablas, listas u otros formatos estructurados. Podríamos considerar la referencia como la inclusión del contenido de la canalización generada automáticamente y de otro contenido que podría automatizarse.
El contenido de referencia aparece en artículos de referencia y secciones de referencia dentro de otros artículos.
- Algunos temas principales pueden requerir su propio artículo de referencia, especialmente si hay una gran cantidad de contenido de referencia, como la sintaxis de búsqueda o la sintaxis YAML en GitHub Actions.
- Para cantidades más pequeñas de contenido o información más específica, como una lista de los idiomas o requisitos de hardware admitidos de una característica, use secciones de referencia en contexto dentro de artículos conceptuales o de procedimientos.
Cómo escribir contenido de referencia
Para obtener la plantilla de contenido de referencia, consulte Plantillas.
- Escriba una frase o una sección conceptual completa para introducir el contenido de referencia.
- Presente el contenido de referencia real de forma clara y coherente.
- En el caso de los temas que tienen un único elemento para explicar, usa una lista.
- En el caso de los temas que tienen varios elementos para explicar, usa una tabla.
- Para contenido referencial más largo, como la sintaxis YAML para flujos de trabajo, usa encabezados de forma coherente.
- Encabezados H2 para cada sección distinta.
- Encabezados H3 para subsecciones, como los ejemplos.
- Ejemplo: Sintaxis del flujo de trabajo para GitHub Actions
Títulos del contenido referencial
- Los artículos o encabezados referenciales de las secciones referenciales describen claramente el contenido de la sección y, por lo general, comienzan con sustantivos.
- Los títulos incluyen suficiente información como para que usuarios novatos puedan acceder al contenido y para describir completamente el contenido de cada sección.
- Los títulos evitan las secuencias de sustantivos. Usa preposiciones para dividir las cadenas de sustantivos largas.
- Los títulos cortos deben ser una palabra o una frase de nombre corto. Ejemplo: "Modelos de IA".
Ejemplos de contenido de referencia
- Artículos de referencia
*
Eventos de registro de auditoría para tu organización
*
Capacidades de roles en una empresa
- "Puntos de conexión de la API de REST para la facturación" en la documentación de las API REST
- "Mutaciones" en la documentación de GraphQL API
- Secciones de referencia en otros artículos
- "Idiomas soportados" en GitHub Mobile
- "Consideraciones de hardware" en Instalación de GitHub Enterprise Server en AWS