This version of GitHub Enterprise Server was discontinued on 2024-01-04. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Troubleshooting content type

In this article

Troubleshooting content includes built-in errors we expect people to encounter, common problems reported to support, and situations people might encounter while completing tasks.

Important

Articles in the "Contributing to GitHub Docs" section refer to the documentation itself and are a resource for GitHub staff and open source contributors.

Use troubleshooting sections in guides or procedural articles to keep solutions close to procedures. Work with support and product managers to surface common errors and include them in the documentation.

Known issues

Known issues are a subset of troubleshooting content specifically designed to respond to bugs, UX/UI issues, and other product quirks that generate a high volume of support tickets. Where troubleshooting content can describe errors that people might encounter, known issues explain problems that people will encounter.

Like all troubleshooting content, known issues can be a section in an article or a standalone article. If a known issue applies to a specific article, document it in that article. If a known issue applies to a specific set of articles or conceptual grouping of features, or if a product or feature has multiple known issues that should be grouped together, create a dedicated "Known issues with NAME" article.

Known issue content for a product or feature does not need to be comprehensive. Unlike other troubleshooting content, some known issues may not have workarounds. The goal of documenting an issue without a workaround is to help people confirm that the issue exists and save them time searching for a solution that doesn't exist yet after GitHub has already determined there isn't a workaround.

Product and feature owners (PMs and EMs) should help plan and review known issue content.

Use known issues to explain the following situations.

  • Product behavior that regularly contradicts people's expectations, but is not yet prioritized for remediation.
  • Behavior that regularly prevents the use of the product or feature for a common purpose.
  • Rare or severe bugs that GitHub has not yet prioritized fixing, and that are not explained in the product or by existing content on GitHub Docs.

How to write troubleshooting content

  • Use any GitHub Docs content type to create troubleshooting sections.
  • Whenever possible, keep troubleshooting content contained within procedural content or guides.
  • You can create a troubleshooting article when it makes sense to keep it separate, such as when there’s a large amount of troubleshooting content on a particular topic.
  • You can create a troubleshooting map topic if a product or feature has many troubleshooting articles, for example "Troubleshooting SSH."

Title guidelines for troubleshooting content

  • Troubleshooting FEATURE
  • Error: ERROR NAME
  • Known issues for PRODUCT

Examples of troubleshooting content