Reference content type

Reference content is consulted for specific pieces of information. It’s information you can quickly check, meaning there’s less emphasis on sentences and paragraphs.

Reference includes information that may be best represented in tables, lists, or other structured formats. We might think of reference as including our autogenerated pipeline content and other content that could potentially be automated.

Reference content appears in reference articles and reference sections within other articles.

• Some major subjects may require their own reference article, especially if there is a large amount of reference content, such as for search syntax or YAML syntax in GitHub Actions.
• For smaller amounts of content or more specific information, like a list of a feature’s supported languages or hardware requirements, use reference sections in context within procedural or conceptual articles.

How to write reference content

For the reference content template, see Plantillas.

• Write a sentence or an entire conceptual section to introduce the reference content.
• Present the actual reference content clearly and consistently.
• For subjects with a single element to explain, use a list.
  • Example: Roles de repositorio para una organización
• For subjects with multiple elements to explain, use a table.
  • Example: Roles de repositorio para una organización
• For longer referential content, such as YAML syntax for workflows, use headers consistently.
  • H2 headers for each distinct section.
  • H3 headers for subsections, such as examples.
  • Example: Sintaxis del flujo de trabajo para GitHub Actions

Titles for referential content

• Referential articles or headers of referential sections clearly describe the contents of the section, and generally begin with nouns.
• Titles include enough information to be accessible to novice users and fully describe the contents of each section.
• Titles avoid stacked nouns - use prepositions to break up long strings of nouns.
• Short titles should be one word or a short noun phrase. Example: "AI Models".

Examples of reference content

• Reference articles
  • 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 in the REST API documentation
  • Mutaciones in the GraphQL API documentation
• Reference sections within other articles
  • "Supported languages" in GitHub Mobile
  • "Hardware considerations" in Instalación de GitHub Enterprise Server en AWS