How GitHub uses GitHub to document GitHub

Garen Torikian

Providing well-written documentation helps people understand, make use of, and contribute back to your project, but it’s only half of the documentation equation. The underlying system used to serve documentation…

GitHub

•

Garen Torikian

•8 min read•intermediate•

--

•View Original

CDNCoffeeScriptHTMLJavaScriptRailsSassXMLYAML

Overview

The article discusses how GitHub utilizes its own platform to document its services effectively. It highlights the transition from a complex Rails application to a streamlined static site using Jekyll and GitHub Pages, emphasizing the benefits of this new setup in terms of speed, ease of use, and collaborative workflows.

What You'll Learn

1

How to leverage GitHub Pages for documentation hosting

2

Why using Jekyll enhances documentation workflows

3

How to implement content references using Jekyll's data files

4

When to use client-side search solutions like lunr-js

Prerequisites & Requirements

Familiarity with Markdown and GitHub workflows
Basic understanding of Jekyll and GitHub Pages(optional)

Key Questions Answered

How did GitHub migrate its Help site to a static Jekyll site?

GitHub migrated its Help site from a custom Rails application to a static Jekyll site hosted on GitHub Pages. This change simplified their documentation workflow, allowing for faster updates and easier collaboration among team members.

What advantages does using Jekyll provide for documentation?

Using Jekyll allows for a streamlined documentation process with features like content references and versioned documentation. It also enhances the speed of the site since it serves static HTML files, eliminating the need for database calls.

What is the purpose of using lunr-js for search functionality?

GitHub switched to lunr-js for a faster client-side search experience, as analytics showed most users relied on external search providers. This change improved the efficiency of accessing documentation without the overhead of server-side search solutions.

How does GitHub ensure the quality of its documentation?

GitHub employs tools like html-proofer to verify that links and images in the documentation are not broken. Additionally, they use CI to ensure that no broken content is published, maintaining a high standard for their Help documentation.

Technologies & Tools

Static Site Generator

Jekyll

Used to build the Help documentation site.

Hosting

Github Pages

Hosts the static Jekyll site for documentation.

Search

Lunr-js

Provides client-side search functionality for the documentation.

Testing

Html-proofer

Verifies that links and images in the documentation are not broken.

Key Actionable Insights

1
Adopting a static site generator like Jekyll can significantly streamline your documentation process.
By moving to a static site, teams can reduce the complexity of their documentation infrastructure, allowing for quicker updates and easier collaboration.

2
Utilizing content references can save time and ensure consistency across documentation.
By defining reusable content in data files, you can maintain a single source of truth for frequently referenced information, making updates simpler and less error-prone.

3
Implementing client-side search solutions can enhance user experience by providing faster access to documentation.
Using tools like lunr-js allows for immediate search results without the need for server-side processing, improving the overall speed and responsiveness of the documentation site.

Common Pitfalls

1

Overcomplicating the documentation setup can lead to inefficiencies and slow updates.

Many teams fall into the trap of using complex CMS solutions that require significant maintenance, which can hinder productivity and responsiveness in documentation efforts.

Related Concepts

Static Site Generation

Documentation Best Practices

Version Control In Documentation