Referential content type

Referential content provides detailed information that people need while they are actively using a feature.

In this article

We create referential articles and referential sections within other articles.

  • Some major subjects may require their own referential article, especially if there is a large amount of referential 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 referential sections in context within procedural or conceptual articles.

How to write referential content

For the referential content template, see Templates.

  • Write a sentence or an entire conceptual section to introduce the referential content.
  • Present the actual referential content clearly and consistently.
  • For subjects with a single element to explain, use a list.
  • For subjects with multiple elements to explain, use a table.
  • For longer referential content, such as YAML syntax for workflows, use headers consistently.

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.

Examples of referential content