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.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.