Writing for GitHub Docs

Follow these best practices to create documentation that's user-friendly and easy to understand.

Our documentation philosophy guides what content we create and how we create it.

Our documentation is translated into multiple languages. How we approach writing the English language documentation can greatly improve the quality of those translations.

We share these principles to design and create the best content for people who use GitHub.

GitHub Docs uses YAML frontmatter and liquid operators to support multiple versions of GitHub with a single-source approach.

You can use Markdown and Liquid to format content, create reusable content, and write content for different versions on GitHub Docs.

You can use YAML frontmatter to define versioning, add metadata, and control the layout for articles.

This guide explains how to create videos that support user needs for GitHub Docs.

You can create reusable content that can be referenced in multiple content files.

You can help users locate elements of the user interface that are difficult to find by adding screenshots to GitHub Docs.

This guide explains when and how to create diagrams for GitHub Docs.

You can use a tool switcher to show how to complete tasks using specific tools.

If an article's title, version, or location changes, you can create a redirect to the current content.

When it's necessary to change the title of an article, the name may need to be updated in several places.

You can annotate longer code examples to explain how they work and how people can customize them for other uses.

This article contains starter templates for the different content types used in GitHub Docs.