Static site generators start to replace web publishing platforms like WordPress

by Tom Johnson on Feb 27, 2015
categories: technical-writing

In the previous post in this series on innovation, I highlighted some web tools worth exploring for help systems. In this post, I want to dive into one of the latest trends with web tools: static site generators.

The Rise and fall of web publishing platforms

For the past 10 years, web publishing platforms with database backends have been the predominant way people publish content online. WordPress and Drupal have dominated the landscape. These web platforms, or web content management systems (CMSs), are so popular, about 22% of all new websites in the U.S. are powered by WordPress (according to TechCrunch).

Drupal tends to be used when you want a more robust (and complex) solution than WordPress. Other tools are also common, such as Joomla, Alfresco, Expression Engine, and more.

However, there's a problem with web CMSs such as WordPress:

• Heavy infrastructure. They require a lot of infrastructure. You need Linux, Apache, MySQL, and PHP (LAMP) configured on a Linux server to run them. You must have the settings just right to avoid errors. In every corporate documentation role I've been in, getting a LAMP architecture installed for documentation has been either prohibited, poorly supported, or riddled with frustrating errors.
• Slow performance: With the database backend, your content is served up dynamically. When the server receives a request for the page, the system (e.g., WordPress) gets the information from the database and assembles the content inside a page template on the fly. The load time for most pages in a CMS is around 3 seconds (around 1.5 to 2 seconds with a CDN). However, many see the dynamic assembly as unnecessary overhead in delivering the page to users. Unless you're constantly changing the content, why not just pre-build the pages? Dynamic assembly creates unnecessary overhead that leads to many problems.
• Security and code mangling. WordPress sites are frequently hacked, which requires web developers to increase security measures. As a result, it can be really restrictive what you can and can't do with code on a page. For example, adding JavaScript in your WordPress page or post requires quite a few hoops to jump through. The WordPress editor consistently mangles code samples, which becomes incredibly frustrating for developers who simply want to publish code tutorials. You pretty much have to convert all the programming syntax into HTML character equivalents. Flipping back and forth between the text and visual editor in WordPress almost always zaps my code samples. And code samples are probably the most important element of API documentation.
• Complexity. Web CMS sites have become far more complex with each release. Now when you install WordPress, there are dozens of core files doing all kinds of things. It makes the software more cumbersome because now you have a lot more interdependent pieces, with a lot of unknown code. Many users want to return to a simpler, more lightweight model.

Hello static site generators

Static site generators are applications that run on the command line and compile a website. For example, you may have various pages defining a layout, some "include" files, a configuration file, and your content files.

The static site generator reads your configuration file and pushes your content into the layout files, adds whatever includes are referenced (such as a sidebar or footer), and renders everything into HTML. Each page has the sidebar and other navigation included directly into it, as well as all the other layout code you've defined, ready for viewing.

Many static site generators run continuously in a browser preview. Each time you make a change to your site, the static site generator recompiles your site in about 1 second. You can refresh your browser preview page to see the changes as you work.

Because everything is compiled locally, you don't need to worry about security hacks into your database. As a result, it's incredibly easy to work with code samples. You can author your content in Markdown or HTML, add code samples inside code blocks that are processed with a Markdown processor (such as Kramdown or Red Carpet), and more. You can add your own scripts directly on the page. It's simply much easier and more flexible to do what you want.

Jekyll, one of the most popular static site generators, allows you to use a templating language called Liquid (from Shopify) inside your content. You can use if-else statements, run loops, insert variables, and do a lot more sophisticated processing of your content through this templating language directly on your page.

Because you're working with text files, you usually store your site files in a code repository such as Github. You treat your content files with the same workflow as programming code -- committing to the repository, pushing and pulling for updates, and more.

When you're ready to publish your site, you can transfer the whole site using the command line to your host. If you're working with Github Pages and Jekyll, your online repository can build your site on the fly. This means your code repository becomes your publishing host. It eliminates the need to actually build your site and deploy the build; instead, you just deploy the source code, and the repository builds it for you.

Static site generator choices

There are many different static site generators available, but most of them work in highly similar ways. Think of them as different kinds of apples -- Gala, Fuji, Granny Smith, Red Delicious, Honey Crisp, McIntosh, Cortland, and more.

When you read the instructions on using a static site generator, most have similar components and workflows -- you have a configuration file, some layout files, allowed programming logic, and so on.

Some of the most popular static site generators include the following:

• Jekyll
• Octopress
• Middleman
• Docpad
• Hugo
• Pelican
• Wintersmith
• MkDocs
• Nanoc

You can see the full list of static site generators broken down by repository numbers at staticgen.com.

When I was trying to choose a static site generator, I chose the most popular one, Jekyll, mainly because I wanted a platform that would have the most community support, momentum, and tutorials available for it.

Jekyll also has the benefit of support from Github, which is the most common code repository on the web. Jekyll and Github are kind of like Mediawiki and Wikipedia -- the software thrives in part from its sponsoring host.

Using Jekyll for documentation

Many of the themes designed for Jekyll involve blogging scenarios, but the sites are used for all kinds of purposes (such as the U.S. government heathcare websites). There are quite a few documentation projects that are using Jekyll. To get a sense of what documentation looks like on a Jekyll site, explore the following sites:

• (Jekyll Docs)[http://jekyllrb.com/docs/home/]
• Sendgrid
• Get Bootstrap
• Github Pages Help
• Scala
• Wistia
• Ionic
• Travis CI
• Mynaweb
• Langhor, Elastich
• Basekit docs

(Note: Special thanks for Erlend Sogge Heggen for pointing me to some of these links.)

You can fork most of the above themes and use them for your own documentation projects. Here are also some Jekyll templates built for docs:

• Jetstrap
• Jekyll docs template

For some articles talking about using Jekyll for documentation, see the following:

• Building Documentation on Jekyll
• How GitHub uses GitHub to document GitHub
• Writing Documentation using Grunt and Jekyll
• How We Document Our Projects With ClojureWerkz Docslate
• Creating Sustainable Documentation with Jekyll

My Documentation theme for Jekyll

I also built a Jekyll theme designed for documentation. You can see the Github repository here: https://github.com/tomjoht/documentation-theme-jekyll. Here's the site: Documentation Theme for Jekyll.

Right now I'm just calling this "Documentation theme for Jekyll." Those are the keywords I kept searching for in looking for documentation-related Jekyll themes, so I decided to use it as the name. If you have a recommendation for something more catchy, please let me know.

What makes a theme specific to documentation?

Any Jekyll site could be used for documentation. So what makes my theme specific to documentation projects?

Without going into too much detail, I'll just note a few features that I thought were key:

• Sidebar navigation
• Search
• Callouts and notes
• Page-based layouts
• Mini-TOCs
• Bootstrap foundation to easily add more components, styles

That's about it. I'll get into this theme in more detail in a future post. I tried to add some documentation for Getting Started, but frankly I've done a poor job here with the theme documentation and need to spend a lot more time on it. Still, you can probably follow it enough to get started.

My plan is to provide a more comprehensive tutorial on using Jekyll from a technical writer's perspective, explaining how to do single sourcing, conditional logic, content re-use, and even things like translation, PDF output, and more.

This is an ongoing project that will no doubt evolve with many iterations and improvements, but I've reached a point where the theme is good enough to start using for documentation.

I'm currently using this theme on a documentation project at work. So far it's going well. It's too early to make any conclusions, but so far my impression is that static site generators may prove to be a platform that works extremely well for API documentation.

Next: 1.9 How to create a help API