Redesigning GitHub’s Help Pages

As a case study, I conducted an audit of GitHub’s current help pages. My goal was to improve usability and accessibility. While rethinking the information architecture (IA) of the help pages, I also took the liberty of updating their design to be more in line with GitHub’s branding.


When a user comes to with an issue, how can I make it easier to for them to find and solve their problem?

Although GitHub already has a wealth of information in their help pages, my ultimate goal was to improve the usability and accessibility of the help pages.

Effective documentation is always important, but especially so if the subject matter is technical in nature and has an upfront barrier to entry.


GitHub already being an established application meant that I needed to follow their design and brand guidelines. Luckily GitHub’s CSS toolkit, Primer, exists to serve as a kickoff/reference point.

Primer: the GitHub frontend bible

I endeavored to follow GitHub’s guidelines while adhering to design principles of accessibility, simplicity, and consistency. The pages needed to portray trustworthiness and approachability through the use of white space, color palette, and typography.

Last but certainly not least, it should be accessible everywhere — usable on any device, using any operating system, at any breakpoint.

Development Process


The first step was researching what makes help documentation pages effective. As I began to gather a list of exemplary help documentation, I noticed certain themes. The best examples had: a prevalent search bar, digestible IA (categorization), and good use of icons/visual aids.

Some great help documentation

I continued my research by examining the documentation of GitHub’s competitors in the online project hosting space. Additionally, I made sure to review the UI of GitHub’s API documentation and other “logged out” (non-application) pages.

Auditing the Help Pages

GitHub’s current text-heavy help page

Armed with the knowledge of what makes effective documentation, I began auditing the current homepage of GitHub’s help documentation. Considering how important well-structured IA is to discoverability on help pages, I immediately knew I’d have to restructure the information’s organization.

Original IA:
A breakdown of the original help page IA (hi-res download at bottom of the page)

The original help homepage is broken down into 3 main sections with a somewhat hidden search bar. Those sections were:

  • Overview
  • Common Issues
  • Categories

The categories section is basically an umbrella housing 38 subcategories.

Proposed IA:
The proposed help page IA (hi-res download at the bottom of the page)

Understanding that this could be simplified, I combed through every subcategory in order to distill relevant themes. My recommendations are to keep the common issues and quick start sections (set up git, create a repo, etc.), make the search field more prevalent, and to breakdown the categories into 6 subcategories:

  • Getting Started: Browse all articles for getting you setup on GitHub and on your computer.
  • Learning Git: Browse all articles on understanding the in’s-and-out’s of Git and version control.
  • Administration: Browse all articles on setting up and managing organizations and teams.
  • Using Browse all articles on the features and offerings of the GitHub web application.
  • Collaborating with GitHub: Browse all articles for collaborating and managing projects using GitHub.
  • Services & Integrations: Browse all articles on GitHub Pages, Gists, and third-party services and integrations.

Creating Page Template Wireframes

Once I had the IA down, I set out to make wireframes for 3 separate page templates that the help section would have access to: an index page, a subcategory page, and an article page.

Help page template wireframes (index page, category page, article page)

I tried to account for as many design considerations as I could, including:

  • How to make search be as prevalent and persistent as possible
  • An options dropdown to select which version of documentation to display ( vs GitHub Enterprise)
  • How to toggle between code examples depending on what operating system you use
  • How the search input and navigation would behave on scroll

Designing the Primer Components in Sketch

The next step was porting the Primer pattern library over to Sketch. To accomplish this, I designed Sketch symbols for the various Primer components. These components where broken down into nine categories: typography, forms, buttons, navigation, alerts, blankslate, avatars, states, and tooltips. If a component had multiple states, those were included as well (eg. hover, disabled).

The idea behind having this pattern library and these components is that it would be utilized on projects going forward. It would allow me to design these pages more efficiently, while enabling me to easily adhere to the established brand and style guidelines. There it can serve as a tool and reference to both designers and developers alike.

The Components:

Designing the Help Pages in Sketch

With wireframes and Primer components in Sketch laying the groundwork, I began creating high-fidelity designs for the help pages. For the help index page I made designs for 3 different breakpoints: mobile portrait, tablet portrait, and desktop. Keeping in line with my wireframes, I also created an example article page.

The help index page at various breakpoints

Taking advantage of my previous work, I was able to reuse multiple Primer components such as typography elements, input fields, buttons, and several octoicons. For example, the article page template uses the menu component in the sidebar (drawing inspiration from the GitHub API documentation).

The article page template


My desire was to create a tone of dependability and trustworthiness, while honoring the brand’s established styles.

I was aiming for approachable yet serious, calming yet professional.

I tried setting this mixture of tone and brand compliance through color choices (blue and different shades of light grays) and deliberate use of white-space (letting the content breathe as to not feel overwhelming).

Additionally, the redesigned help pages should provide more guidance to a user who isn’t exactly sure where to find the answer to their question. I tried accomplishing this by using both subtle iconography and making the Help Topic sections the first, most prominent section under the jumbotron. I kept the Quick Start and Common Issues sections but provided guidance using descriptive text and highlighting key words/topics in bold.

Coding A Prototype

The final step in this process was creating a working prototype. Using Node and Gulp, I was able to get a build up and running. I configured gulp-sass to watch and compile my Sass while utilizing npm to pull in the Primer dependencies.

I reused components wherever and whenever possible. Pulling down the Primer dependencies allowed me to write less one-off CSS statements. I modularized as many of the styles as I could by creating variables and utilities; I even created a card component that I was able to reuse in multiple sections on the page.

Primer’s grid system didn’t really have any responsive styling out of the box, so I had to take liberties with that. Drawing inspiration from Bootstrap, I made the columns stack as the viewport width gets smaller.

I managed my code using GitHub and deployed the final product to GitHub Pages at:

The final product!


Overall, I was very satisfied with how much this process sped up the actual design, development, and iteration of the project. I learned that the investment in creating a design system exponentially improves the software development process. It promotes consistency and cohesion, speeds up the team’s productivity, establishes a more collaborative workflow, and serves as a future-friendly foundation for the application.*

If GitHub followed through with my ideas, I believe it would directly improve user retention (a positive experience would make customers less disgruntled). Indirectly, I believe it would serve to unify and strengthen the GitHub brand.

Next steps in this process would be to build out the category and article page templates.

Closing Remarks

This article serves to provide insight into my way of thinking and building products. Every web development project requires translating a vision into a reality, and the process of taking an idea from concept to completion is an undertaking which I find highly rewarding.