Creamos artículos referenciales y secciones referenciales dentro de otros artículos.
- Algunos temas principales pueden requerir su propio artículo referencial, especialmente si hay una gran cantidad de contenido referencial, 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 lenguajes admitidos o los requisitos de hardware de una característica, usa secciones referenciales en contexto, dentro de artículos conceptuales o de procedimientos.
Cómo escribir contenido referencial
Para obtener la plantilla de contenido referencial, consulte "Plantillas".
- Escribe una oración o una sección conceptual entera para introducir el contenido referencial.
- Presenta el propio contenido referencial 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 diferente.
- Encabezados H3 para subsecciones, como los ejemplos.
- Ejemplo: Sintaxis del flujo de trabajo para Acciones de GitHub
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.
Ejemplos de contenido referencial
- Artículos referenciales
- Accesos directos del teclado
- 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 referenciales en otros artículos
- "Supported languages" en GitHub Móvil
- "Hardware considerations" en Instalar el servidor de GitHub Enterprise en AWS