Building Documentation on Jekyll

For any technology company, having accurate and up-to-date documentation for customers is absolutely essential. There are many tools that you can use to create and maintain docs. Here at Wistia, we took a different approach; our Customer Happiness team decided to use something that’s mostly known for blogging as our documentation solution.

Meet Jekyll. It’s an open-source library written in Ruby (a.k.a. a “gem”), and it’s been around since 2008. Jekyll is very popular amongst the developer crowd for its simplicity and flexibility. Most people use it to create static websites, like personal blogs.

At Wistia, we discovered that the very reasons that Jekyll is great for blogging also apply for documentation. If you are comfortable with basic HTML and CSS, or if you’re interested in learning and feeling a little adventurous, it’s definitely worth looking into. Here’s why:

Jekyll is not a Content Management System

We’re all familiar with the powers of a CMS. In theory, they are the ideal, holistic solution for content, from creation to publication. In practice, however, they can add a lot of dead weight and distract from content creation. Some systems are so complicated that you might spend longer setting up the CMS than actually writing the documentation.

With Jekyll, there’s no signing up, no emails to verify, and no credit card numbers to give out. Just download the gem and immediately get to work creating content.

Learn useful, repeatable front-end development skills

Wistia’s documentation is mostly written by our Customer Happiness team. They interact with customers on a daily basis, so they know the best ways to support them. Through Jekyll, every member of the support team has gotten exposure to front-end technologies like HTML, CSS, and Javascript.

The same skills acquired through Jekyll are repeatable and valuable elsewhere. For example, Wistia Support Central and the Bandwidth Predictor were entirely created by our support team. Furthermore, some of the coolest Wistia Labs are the brainchildren of the support team! As a technology company, it makes a lot of sense for all of us to learn repeatable, modern technologies that are relevant to our product.

Get experience with Git

Speaking of repeatable skills, Git is an amazing version control tool. Most of the time, it’s used only by software engineers. Using Jekyll for documentation naturally leads to storing it as a repository on GitHub. (Fun tip: it’s open-source, meaning anyone can send “pull requests” to make changes to the doc).

Anyone who has used Git before knows that it’s extremely powerful and absolutely essential for collaborating on software projects. However, it is not the most intuitive tool to learn, and it may seem quite intimidating at first. Using Jekyll has not only given the support team a chance to use front-end technologies, but also proven to be a good starter project to learn Git and become comfortable with its basic commands.

Get started with Jekyll!

Jekyll is an awesome tool for creating and maintaining support documentation. If you are interested in getting started with Jekyll, I’d highly recommend the following resources:

• Official Jekyll Guide for getting started quickly
• Octopress for common plugins and addons
• GitHub Pages for free hosting of Jekyll sites
• Jekyll Tips for some tips on adding Disqus comments, social media widgets, Google Analytics, etc.