A fellow recently asked me for advice about running a Ruby workshop. And folks, I had forgotten I knew so much about it before he asked!

Before Rebuilding Rails had a video class, I had written a lot of the material for Rebuilding Rails workshops that I gave at Southeast Ruby and at Railsconf. I got to run a whole roomful of people, for multiple hours, over that code, trying to get everybody to get exactly the same result. Oy.

Running a workshop where people type and run the code is an unusual situation. It changes how you present. And it changes how you write the code.

In his case, this was an intro workshop about $NAMEOFTECHNOLOGY. He wanted people to build a demo, get some good experience and come away wanting to learn more. Great! That’s a fantastic goal for a workshop at a conference.

Here’s What I Told Him

First he needs a resource page — a list of documentation, tutorials and so on for people who want to know more. He should promise the resource page at the beginning of the talk and then not give it out until the end, so that his fastest, best, brightest students aren’t ignoring him through the whole workshop to do their own thing.

If possible, he should have a teaching assistant. If you’re trying to get a whole roomful of people to do the same thing all at once, “one” is not enough people. Your TA doesn’t have to be utterly familiar with the material. Just having somebody competent and energetic to help people with quick problems will speed everything up a lot.

You want a code repository to follow along in, with git tags or similar for each chapter-sized section. Then if somebody is having trouble, they can do a quick “git checkout” to catch up at the next chapter. They can also peek ahead to compare their code and see what’s different. It’s also a lovely record of the code for post-workshop reference.

The demo code should start with a deploy. The early steps should involve making something runnable and workable that they could show off to friends even if they don’t get far. Workshop attendees are not like coworkers: some will be very highly skilled and some will be of very low skill, randomly. That means getting everybody to do the same thing is going to move much, much more slowly than you think because you’ll be waiting for the novices, while trying to keep the old hands from getting too rowdy.

The demo code should be in small steps so that you can run them quickly. If somebody makes a typo on the first slide of code, you do not want them to have to wait for two more full slides before finding the typo. Each runnable step should be very quick, no more than a slide or two. Otherwise you’ll have a whole roomful of people trying to check the code from the last three or four slides, all at once. You can only have one displayed at a time.

The code must be short and to-the-point. You need big fonts for everything, including code. And you only get a slide or two for each runnable feature. So review your code over and over. Could you split a feature into two smaller features? Could you do the same thing with fewer lines? Could you cut out a bit of error handling in favour of letting them type less? This is a learning workshop, not a finished commercial product.

Slides that change code must highlight the changed code, perhaps by circling the few words that changed or using a different colour for the lines that are different. If you’re changing code, make it extremely clear what changed and what didn’t.

Put your code and text onto slides as early as possible. You don’t know how much room they’ll take up with the large fonts and weird sizes of slides until you’ve put them there. Having a single too-long line can be the difference between two slides and three. Put everything onto slides, at the correct sizes and aspect ratios, very early in the process. It will show you your trouble spots while you still have time to fix them.

Before the workshop, run through the code with somebody who’s never seen it. Multiple people is good, especially if they are consecutive, not simultaneous. You need to find problems, fix the problems, try again and find more problems. Even just one or two run-throughs will find a lot of trouble before you have to handle it in a roomful of thirty-plus strangers who are all stuck waiting for you.

I mentioned this earlier, but it’s important enough to say twice: big fonts, big fonts, big fonts. Text should be large and clearly visible. For the English text, put a few key words or sentences on the slide and the rest in presenter notes. For the code, cut it down to short line lengths and few lines per slide. Cut, cut, cut that code. If you’re working in a nice terse language like Ruby or Python it will make your life much easier.

And An Example

To show that I practice what I preach, here’s a workshop based on Rebuilding Rails that I gave in 2019 at a couple of conferences. I’d do a few things differently now, but it hews pretty close to my advice above. I did give it with a TA. You’ll see him credited on the title slide. And we helped over a hundred people spend three hours typing it at RailsConf, with all the desks full and people sitting in ones and twos, up and down the aisles.

I’m told it was a good one.

When You Run Your Workshop…

I normally end with a summary here. But this post is so dense that it’s basically all summary.

This should sound like you could do a lot of work on your workshop. And that’s definitely true. I gave it at several conferences, which helps spread the load a bit. Workshops tend not to be recorded, so giving them repeatedly is good. I expect if Covid hadn’t hit when it did, I could have given a lot more of this workshop.

Instead, it was the beginning of the video class for Rebuilding Rails and it sells pretty well. So if people want to hear what you’re saying, you have options to reuse it for a bit of fame or profit.

It is a lot of work, but it can help you in the long run.