Search results

Slides for Writing Tech Docs Like a Hacker with Jekyll presentation

by Tom Johnson on May 17, 2016
categories: jekyll

Here are the slides for my STC Summit 2016 talk on Writing Tech Docs Like a Hacker with Jekyll presentation. In this presentation, I introduce the tech comm conference attendees to Jekyll and how it can be used for authoring technical documentation. I'll try to demo a few of the tasks I describe.

My slides are linked below (format is RevealJS):

Here’s the description of my Jekyll presentation:

Writing tech docs like a hacker with Jekyll

Static site generators are a new breed of documentation tools that are much more common in engineering groups where developers contribute to the documentation.

Jekyll is one of the most popular static site generators, but it is highly similar to others in the same category such as Docpad, Middleman, Wintersmith, and Octopress. You can see a more comprehensive list of the top static site generators at

Jekyll projects approach doc as code. All the files are open and editable within a code editor, and your files can live in the same repository as your program code or within the same version control workflow.

Although developers and web engineers love Jekyll, there are significant challenges to overcome when adopting Jekyll for any robust tech comm publishing scenario. Some of these challenges include conditional filtering, single sourcing, PDF output, a robust TOC, search, context-sensitive help, collaboration, SME review, and more.

In this presentation, I’ll share my adventures in using Jekyll and how I dealt with each of these challenges.

Unfortunately, the recordings are only available to Summit attendees, those who are attending the Virtual track, or those who buy the Summit Playback package.

I’m giving a similar presentation to the STC Silicon Valley chapter next week (and I’ll record and post that one).

About Tom Johnson

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.