Open Source Slides

In August, our training program hits the road at Lone Star Ruby Conf in Austin, TX. Registration for our September Ruby on Rails training is also now open. It marks our one-year anniversary of running Ruby on Rails training classes!

We’ve learned as much as our students. I’d like to focus on one area: slides.

  • Problems with slides

    The format of our class is workshop-oriented, with lectures leading into each workshop. Over time, the lectures built up an arsenal of over 1150 slides.

  • No portability, not open source

    The slides were all in Keynote but not everyone at thoughtbot is on OS X.

  • Style

    Achieving beautiful syntax highlighting involved a dance of writing the code in Textmate, then copying as RTF using Dr. Nic’s bundle.

    Changing our design of the slides would be painful. We use master slides, but this could be better.

  • Not executable

    If we wanted to run the code, we had to copy it back into an editor or shell to run it. Sometimes there are hidden characters that come along for the ride. Ruby freaks out on these characters.

  • No regression suite

    Slides tend to be error-prone and we don’t have a regression test suite for it.

  • Format conversion

    Delivering PDFs to students is time-consuming since the rate of change for slides is high and the conversion-and-sharing process is slow.

  • Versioning

    Versions are non-existent. Trying to maintain Keynote slides in git, our preferred version control system, is good for backups but bad for diffs. There may be better tools out there for versioning these kind of files, but why bother? I’d rather use our familiar file-based tool.


A few weeks ago, I began converting Keynote slides into Markdown. The process is simple: run *.md files through slidedown by Pat Nakajima.

gem install slidedown

Create some slides quickly and easily:


## why automated tests?

![Quizzical puppy](/images/quizzical_puppy.png)


* prevent regressions
* prove functionality with executable code
* enable refactoring
* think about the interface before implemenation

Then convert:

slidedown --template=import > tdd.html

Example output

Open source, familiar tools

This generates HTML markup that can be manipulated in the usual way: CSS for style and Javascript for behavior (transitions).

We can continue using git. Look at this beautiful diff!


Integration with business processes

We looked at the PDF conversion process as a business process problem. I had been scp'ing HTML syllabuses and PDFs to one of our servers and pointing students to that URL. This was a lightweight solution at the beginning that hasn’t scaled well over time.

Now that the core materials have been converted to our most-natural formats, we decided to create a legitimate training application.

class SlideshowsController < ApplicationController
  before_filter :authenticate, :authorize

  def show
    if file_exists?(file)
      render :file => file
      render :nothing => true, :status => 404 and return false


  def file
    File.join(directory, "#{params[:id]}.html")

  def directory
    File.join(RAILS_ROOT, "app", "views", "slideshows")

  def file_exists?(path)

Using a similar pattern that we use for PagesController (static pages like about and contact us) and using Clearance for authentication, we quickly had the start to our application.

The possibilities from here are many… automated tests?

We hope to bring together more business processes that have grown out of the training program over the last year into a system based on tools that we use every day.