May 23, 2016: 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 Staticgen.com.

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.

About Tom Johnson

tomcrabTom Johnson is a technical writer for Amazon Lab126 in Sunnyvale. He regularly publishes posts, podcasts, and video about technical communication at idratherbewriting.com. He currently helps organize the programs for both STC Silicon Valley chapter and Write the Docs SF.

Meeting details

Date: Monday, May 23, 2016
Networking/social time: 6:00-7:00pm
Presentation time: 7:00-8:00pm+
Location: IHOP Restaurant, 4200 Great America Parkway, Santa Clara, CA 95054
Cost: Free

Note: You don’t have to be an official STC member to attend the meetings.

Slides

This entry was posted in Past meetings. Bookmark the permalink.