Experimenting with Jekyll for tech comm
Today I had the opportunity to explore Jekyll a bit more. Jekyll is a static site generator that helps you build websites quickly. The sites can be blog sites or regular sites (or documentation sites). However they're used, there's definitely a trend toward static site generators over database-driven sites.
Seven years ago, online CMS platforms backed by databases were all the rage. WordPress, Joomla, Drupal, Alfresco, Blogger, Typepad were all popular. And wikis were also springing up: Mediawiki, MoinMoin, Tikiwiki, Dokuwiki, Phpwiki, and so on.
Now the winds have blown a different direction. People are tired of heavy database models. Every time I go to my site (built on WordPress) and look for a post, I curse under my breath waiting for pages to load. It all feels so slow, bulky, and unnecessarily cumbersome. Have you ever looked through all the files in a WordPress installation?
The trend toward static site generators is a movement toward simplicity. We don't need databases and heavy infrastructure. Mostly we're just writing, after all. You can build your site on your local machine and use source control via your command line to publish it.
Popular static site generators include Jekyll, Middleman, Wintersmith, Octopress, Pelican, Brunch, Docpad, and more. See Staticgen for a list of more than 50 static site generators, with names as creative as "Broccoli Taco" and "Monkeyman."
In my trends post, which had a lot more reads than I ever imagined, I hinted at the idea of switching to a platform that offers Markdown. I've been tinkering off and on with this idea for months now. When I read a bit more about Github's authoring process, I felt the time was right to pilot an experiment.
In looking at all the static site generators, I decided to stick with the most popular one: Jekyll. Jekyll is popular in part because it integrates with Github Pages, which is free, so as long as Github continues to be the default source control on the web, Jekyll is going to be well-supported and its community large.
With any open source project, the size of the community determines the number of plugins, themes, tutorials, longevity, and general information online about the platform.
I'll be posting more about Jekyll in the weeks to come. Jekyll is pretty easy to figure out (after all, minimalism is part of the point). But there aren't many tutorials that address Jekyll from a technical writing point of view.
From what I can tell, most of the features a tech writer needs are available through Jekyll and the Liquid markup. For example, conref, content re-use, variables, conditional filtering, search, export, comments, syntax highlighting, tags, etc. are all possible. Jekyll's main appeal, however, is the fact that it's a modern web platform, built by contemporary web designers and engineers, with a community that is quickly gaining momentum on the web.
If you're using Jekyll for documentation, let me know.
