^{Company, Technical}

Creating Sustainable Documentation With Jekyll

_{SendGrid Team

August 20, 2013 • 4 min read}

I’ve spent a big part of the last year working on documentation for SendGrid. I’ve learned a lot of things. You can read about how we broke down the problem of documentation at a high level and why documentation is critical for success in Cheat Codes for Good Documentation.

Below you’ll find the path we took, from the early days through last November’s switch to the current system, based on Jekyll. Most of what I’ll recommend applies to documenting an abstraction layer, e.g. an API.

Scope of SendGrid’s Docs

Just for context of what SendGrid’s docs look like, here is the output of a linklint check.

35 directories with files 6 default indexes 230 html files 1 image file 77 other files 113 http links 28 https links 1 mailto link 1155 named anchors

Note: there is only 1 image file because images that are small enough are converted to embedded URI data and stored in the css. This is accomplished using juicer.

History of SendGrid’s Docs

The Early Days: Wiki-style

June 2009 – April 2011

The initial documentation was basically the Minimum Viable Product for docs. A wiki required minimal effort on the platform and backend. It was easy to add and edit info, but hard to do complex layouts. A lack of constraints lead to inconsistency across similar pages.

WordPress

April 2011 – November 2012

WordPress was a step in the right direction but ultimately the wrong tool for the job.

Benefits:

Easy to edit content
Easier to admin than wiki
More customizable than wiki, but not easy

Costs:

Potential security issues (ops says “not on our network,” third parties iffy)
Change control is hard
Lots of dependencies
Slow load times
Fragile — easy to bring down production.
Sucks at handling code

WordPress will drive you mad.

Lessons Learned

Content and coverage is not enough.

We had decent content and product coverage but our documentation lacked consistency, organization, and any sort of user experience guidelines.

We weren’t giving users enough tools to self-serve and succeed. Our platform was getting in the way of our goals rather than helping us.

What Does Sustainable Mean?

We knew we needed more sustainable documentation. By sustainable I mean:

Change tracking
Ease of deploy
Maintainability of platform
Smart constraints
Smart defaults
Ease of editing content
Defined structure

Not surprisingly, these are a lot of the same things that make code sustainable.

Our Criteria

Version Control
Continuous Deploy (not for 1.0, but eventually)
Won’t make ops think twice about security
More robust platform

Robust for us meant a better platform in terms of reliability, scalability, speed, and customization than our existing solution.

We were willing to make tradeoffs in order to get a more solid platform, such as requiring a development environment to contribute docs, and requiring knowledge of HTML or markdown.

Our best option started to sound a lot like a static site.

Docs Built on Jekyll

November 2012 – Present

“Jekyll is a simple, blog aware, static site generator.”

Jekyll was created by Tom Preston-Werner (github) and Nick Quaranto (37 Signals).

It is a static site generator takes a bunch of templates, augments them with data and output from plugins, and outputs a complete HTML site that requires only a web server.

What is a Static Site Generator?

Static site generators can be found in many languages. Jekyll is written in ruby, so custom plugins are written in ruby. The templating language for Jekyll is called liquid, created by Shopify. If you don’t write ruby, chances are you can find a solid static site generator written in your language of choice.

Keep in mind that a static site truly means static. You have no access to any GET or POST data and no access to querystrings. If it’s not available at compile time, you can’t use it.

Who Uses Jekyll

37 Signals
Awe.sm
Github Pages
Twitter Bootstrap

GitHub pages use Jekyll, with some limitations. No custom plugins are allowed.

But you can actually host any static content on github pages, so if you generate the site locally you can use custom code.

What Does Jekyll Look Like?

Typical Jekyll Scaffolding

Layouts reference includes, and posts and pages reference layouts. In most cases you will probably have an assets folder as well for holding things like images and scripts.

YAML Front-matter

What the heck is front-matter? I don’t really know and it seems like a terribly non-descriptive name for such an important component of the system.

In simple terms, the front-matter is a file-level configuration header. Any file that has it will be processed by jekyll. You can add arbitrary metadata to the header and use it in your pages and layouts.

Basic YAML Front-matter Example

--- layout: page title: Docs Home ---

Customized

--- layout: page title: Docs Home icon: icon-home showTitle: false navigation: show: true ---

Basic Layout Example

<html> <head> <title>{{ page.title }}</title> </head> <body> {% include header.html %} <div class="container"> <article id="content"> {{ content }} </article> </div> {% include footer.html %} </body> </html>

Basic Page Example

--- layout: page weight: 0 title: Python navigation: show: true --- We'll start with a simple example using the built-in Python SMTP libraries to send a message. After that example, you can find more complete instructions that use the SendGrid Python library. {% anchor h2 %} Using Python's SMTP Library {% endanchor %} This Python program will build a multi-part MIME email and send it through SendGrid. Python has built in libraries to send and receive emails. This example uses: * [smtplib](http://docs.python.org/library/smtplib.html) * [email](http://docs.python.org/library/email.html#module-email)

Custom Liquid Block Example

#Generates a named anchor and wrapping tag from a string. module Jekyll class AnchorBlock < Liquid::Block def initialize(tag_name, markup, tokens) @tag = markup super end def render(context) contents = super # pipe param through liquid to make additional replacements possible content = Liquid::Template.parse(contents).render context #strip out special chars and replace spaces with hyphens safeContent = content.rstrip.gsub(/[^\w\s]/,'').gsub(/[\s]/,'-') output = "<#{@tag} class=\"anchor-wrap\"><a name=\"#{safeContent}\" class=\"anchor\" href=\"##{safeContent}\">" output += '<span class="anchor-icon"><i class="icon-link"></i></span></a>' output += content.strip output += "</#{@tag}>" output end end end Liquid::Template.register_tag("anchor", Jekyll::AnchorBlock)

Plugin Example

module Jekyll require 'haml' class HamlConverter < Converter safe true priority :low def matches(ext) ext =~ /haml/i end def output_ext(ext) ".html" end def convert(content) begin engine = Haml::Engine.new(content) engine.render rescue StandardError => e puts "!!! HAML Error: " + e.message end end end end

Challenges Implementing Jekyll

Longer initial development time — 2.5 months for 1 developer
Converting content from WordPress was basically an ETL project.
Dependencies can be a challenge for new contributors
- Uses metadocs on configuration
- Provided screencast on how to contribute via github web UI
- Screencast on how to fork repo, make change, and submit pull request
Third party JavaScript-based utilities are needed for search, comments, etc

…but it feels like we got it right.