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 模板.

• 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: 组织的存储库角色
• For subjects with multiple elements to explain, use a table.
  • Example: 组织的存储库角色
• 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: 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
  • 组织的审核日志事件
  • 企业中角色的能力
  • REST API 的计费终结点 in the REST API documentation
  • 突变 in the GraphQL API documentation
• Reference sections within other articles
  • "Supported languages" in GitHub移动版
  • "Hardware considerations" in 在 AWS 上安装 GitHub Enterprise Server