Tipo de contenido referencial

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, consulta 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.
  • Ejemplo: Roles de repositorio para una organización
• En el caso de los temas que tienen varios elementos para explicar, usa una tabla.
  • Ejemplo: Roles de repositorio para una organización
• 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