I recently put together a 90-minute workshop on unit testing and Heroku deployments for Dev Together. The workshop’s purpose was to serve as an intro to what unit testing is, how to write basic unit tests, how to unit test your React components using Facebook’s recommended testing libraries, and how to deploy a React application to Heroku. As the facilitator, I would be live coding and having the audience code along with me during the exercises. This was a lot of content to deliver in 90 minutes and was definitely a learning experience in preparation and facilitation. I’ve compiled my biggest takeaways from this experience to hopefully help you with your next workshop prep.

Document the environment setup and share ahead of time

Document all of the prerequisites for the workshop and how to set them up.

Think about

• What tools will you be using during the workshop?
• If you are using an IDE (integrated development environment), will the attendees need to use the same IDE or any IDE?
• Will you be using the command line? If so, what command line tools or interfaces will need to be installed ahead of time, e.g. Git?
• What package manager will you be using?
• Will you be using any IDE or bash extensions during the workshop?

While you’re documenting the setup that attendees will see during the workshop, make sure to describe what each tool is used for and call out which ones are required and which ones are optional. It can be confusing as an attendee to see the facilitator’s IDE behave differently than yours if you don’t know that they have a bunch of extensions and custom configuration causing that behavior. As an example, this is my environment documentation for the workshop I put together.

Once you have the recommended environment for the workshop documented with instructions on how to set it up, make sure to share that documentation with attendees prior to the workshop. I recommend sharing enough in advance so they have the weekend before the workshop to get everything set up, but at least a day ahead of time minimum.

Limit dependencies

If you will be live coding and having attendees set up a project and code along with you, limit the number of dependencies in the project. The goal is to make the project as easy to set up as possible. The easier the project is to set up, the more likely everyone will be successful getting it running on their machine and will be able to follow along with your content. The fewer dependencies you have also means that attendees will have fewer tools and libraries to learn and understand while working to understand the concepts that you’re planning to cover.

Limiting dependencies also has the added benefit of making the project more evergreen. The fewer dependencies you have to manage and upgrade as time goes on means the longer that content is reusable for future workshops.

Work time into the agenda for project setup

We all know that not everyone will come prepared for the workshop. People have a lot of other priorities and setting up for your workshop might not be high on their list. I found it useful to start the workshop with some introductory content, letting people know that they could go ahead and follow the instructions to get the project set up while I talked.

Giving everyone permission to set up the project while I reviewed the goals of the workshop, an overview of the project, and an introduction to what unit testing is made sure that no one felt ashamed of using the time to get caught up and that everyone was ready when I started the code portion of the workshop.

Make branches for each exercise of the workshop

Every audience has differing skills and experience levels. Prepare for that by creating branches for each transition point in the workshop that will have all the code that has been covered up to that point. We all know how frustrating it feels when you fall behind and struggle to catch back up. If someone fell behind during one of the exercises, they can check out the next branch and start the next exercise at the same point as everyone else. With this strategy, everyone will also have a reference for the finished code of each exercise to go back to if they want to review the content of the workshop.

This can also be used if there is a lot of boilerplate or setup code that needs to be written. You can make a new branch and commit the boilerplate code for everyone to check out. This will save you time in the workshop so that people aren’t writing out a lot of imports, test data, or config.

As an example, see the branches I created for my workshop.

Make descriptive commits

However, for this branching strategy to be useful for your attendees, your commits must be clear, descriptive, and informative. Make sure that they are organized in a logical fashion and that the messages are useful. Include links to documentation and information about why the code looks and behaves the way it does. Look at this commit to see what I mean.

Your commit history should be a step-by-step instruction guide for your attendees of how to complete the exercise. This requires planning, intentionality, and probably quite a bit of git rebase -i to be successful.

Provide exercises and code samples in written form

It can be hard as an attendee to follow along with someone typing depending on how fast they type, how fast they talk, where the screen is, etc. Plan your exercises and sample code ahead of time and type it out into some form of documentation to provide your attendees during the workshop. This will further help them follow along as you code and help them should they fall behind or get stuck.

This is also super useful if they want to review your workshop later and revisit some of the concepts or code. This is what I put together for the unit testing portion of my workshop.

Practice, practice, practice

Coding in front of people is TOUGH. Public speaking is TOUGH. Make sure you practice your workshop several times. I’ve found that when I practice workshops, I like to end with quite a bit of a time buffer because a workshop with real humans takes a lot longer than my practice session. For reference, my 90-minute workshop only took 60 minutes during my practice run-through and 80 during the actual event. When you’re doing the live workshop, there are more questions, you type slower, and there is more explanation to provide. If you can practice the workshop with people ahead of time, even better! Get their feedback and work through the parts that are less clear.

After my workshop, I received a lot of positive feedback from using these strategies and I will definitely use them in workshops going forward. I learned a lot about how much content to prepare for a workshop and next time, I will limit the content to be much smaller in scope. I hope these tips help you with your next code-along and if you have more, please share them with me. Tweet me @mercedescodes.