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.
- Example: Repository roles for an organization
- For subjects with multiple elements to explain, use a table.
- Example: Repository roles for an organization
- 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: Workflow syntax for 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.
Examples of referential content
- Referential articles
- Keyboard shortcuts
- Roles in an enterprise
- REST API endpoints for billing in the REST API documentation
- Mutations in the GraphQL API documentation
- Referential sections within other articles
- "Supported languages" in GitHub Mobile
- "Hardware considerations" in Installing GitHub Enterprise Server on AWS