Skip to main content

Writing for GitHub Docs

Learn about writing for GitHub Docs.

Best practices for GitHub Docs

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

About GitHub's documentation philosophy

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

Content design principles

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

Writing content to be translated

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

Making content findable in search

Follow these SEO best practices to help users find GitHub documentation using search engines.

Versioning documentation

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

Using Markdown and Liquid in GitHub Docs

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

Using YAML frontmatter

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

Using videos in GitHub Docs

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

Creating reusable content

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

Creating screenshots

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

Creating diagrams for GitHub Docs

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

Creating tool switchers in articles

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

Configuring redirects

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

Changing an article's title

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

Annotating code examples

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

Templates

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