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.

Solutions

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
vim tdd.md

Create some slides quickly and easily:

!SLIDE

## why automated tests?

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

!SLIDE

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

Then convert:

slidedown tdd.md --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
    else
      render :nothing => true, :status => 404 and return false
    end
  end

  protected

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

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

  def file_exists?(path)
    File.file?(path)
  end
end

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.

Hound automatically reviews Ruby, JavaScript, and CoffeeScript code in your GitHub pull requests and comments on style violations. It is free for open source repos and $12/month per private repo.