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 Modèles.

• 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: Rôles de dépôt pour une organisation
• For subjects with multiple elements to explain, use a table.
  • Example: Rôles de dépôt pour une organisation
• 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: Syntaxe de flux de travail pour 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
  • Événements du journal d’audit pour votre organisation
  • Compétences des rôles dans une entreprise
  • Points de terminaison d’API REST pour la facturation in the REST API documentation
  • Mutations in the GraphQL API documentation
• Reference sections within other articles
  • "Supported languages" in GitHub Mobile
  • "Hardware considerations" in Installation de GitHub Enterprise Server sur AWS