Recording: Writing tech docs like a hacker with Jekyll
You can view the slides here.
Here’s the recording:
If you just want the audio, here it is:
Listen to this presentation:
Here’s a description of the presentation from the Southern Ontario STC.
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, Tom Johnson will share his adventures in using Jekyll and how he dealt with each of these challenges.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
About Tom Johnson
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.