Lessons Learned in Preparing for an Internet-Free Technical Tutorial

Last year at Agile 2010, Abby Fichtner and I did a technical half-day tutorial involving FitNesse and some code. We first presented a few examples together, and then intended to walk the audience through a series of stories themselves. We ran into common issues:

• We gave the attendees usb sticks and CDs at the beginning of the tutorial, and many of them were distracted and not listening while we gave our introductory information
• I would estimate that 40% of the people had issues with installing and starting the software (Java, Eclipse, FitNesse). After spending WAY TOO LONG trying to get everyone up and running (I saw some errors I had NEVER seen before!), there were still a significant number of people unable to run successfully
• I believe we had some assumptions/expectations about the attendees -- things they would be able to do already (like use Eclipse), that many of them struggled with.

So this year, when I was going to give a half-day tutorial at STAREast on using FitNesse and Selenium, I spent a lot of time beforehand making sure that I could avoid some of these pitfalls. In the end, the tutorial went as smoothly as I could have asked, so I thought I would share what I considered, learned, and ended up with.

My final environment, delivered on USB sticks that I gave to each attendee (I got lucky with all computers that had USB ports in the room!), had the following on it:

• An installer for VirtualBox for windows
• An installer for VirtualBox for mac
• An Ubuntu virtual machine, outfitted with the following:
• The download from the SeleNesse web site, which includes:
• FitNesse
• SeleNesse library
• I added the Selenium Server from Selenium 2.0b4
• A double-clickable shell script that did the following:
• Started FitNesse on port 8080
• Started the Selenium Server
• Opened firefox, to http://localhost:8080
• Inside the FitNesse directory was a page called HtmlElements. The origin/idea came from the original SeleNesse download, which I credited to Marisa Seal, who credited it to Gojko Adzic (Thanks, Gojko!). This page gave me a website to test against, since there was no internet connection. (See Lesson 0 - what to test)

To get them up and running, they had to do the following:

• Install VirtualBox (which could be done from the USB stick directly (See Lesson 1 - admin rights))
• Copy a folder called SE2011 from the USB stick to their computer, to a location they could find (See Lesson 2 - running from usb is SLOW)
• Either double-click the SE2011.vbox file in the local SE2011 folder, or go into VirtualBox and click Machine->Add and add the SE2011.vbox file.
• Select the SE2011 VM and click Start

Once they were in the VM, they had to open the SE2011 folder and double-click on the StartTutorial.sh file, then click the Run button.

I saw 2 hiccups during this session that I wasn't expecting:

• On Windows XP (I had tested on Win7), installing VirtualBox threw up a warning involving security of virtual interfaces. Allowing the install anyway did not prove to be problematic for the 2 people who had this issue.
• 1 person's VirtualBox didn't have a Machine->Add menu. Not sure if they had the same version or a previous one, but we worked around it.

So, how did I get there?

Lesson 0 - what to test
I knew going into this tutorial that there would not be internet access in the tutorial room, and that I was going to have to provide something to test that could be run locally. Last year, when I did a non-interactive talk on the same subject, I was running a local Windows website that I had installed into IIS previous to speaking. This time, I didn't want the extra step of having a website that had to be installed and started locally in order to test it, especially since the things we could fit into a tutorial would be pretty simple.

Being able to add HTML elements to a local FitNesse site was convenient for a variety of reasons:

• It avoided another piece of possible setup/configuration complexity
• It gave me an easy-to-edit controlled environment to add simple examples to test
• The learning curve for what was on the site was minimized

How I came to choose this environment
The first thing that was suggested to me for minimizing set up and configuration issues at a tutorial was a bootable USB stick. There are several resources out there for creating bootable USB sticks with Ubuntu (whatever) edition on them, and NetBook edition was suggested to me.

I tried for many long hours to make this work, and used at least three different methods for creating this bootable USB stick. Not one of them would boot from *my own* macbook pro. If I couldn't get it to work at home, I couldn't have any confidence in it at a tutorial. Even then, I still had lingering questions about being able to save a machine state and allow them to boot into the usb and then have the ingredients I needed them to have, and I had questions about speed.

After burning 10-15 unsuccessful hours on this bootable stick idea, I decided I would shoot for a Virtual Machine, with some kind of client player for them. I looked at VMWare, which I happen to enjoy. The VMWare Player is free for Windows, but VMWare Fusion for Mac is a paid-for application. Buying licenses for each USB stick wasn't an option, so I looked at VirtualBox. I was able to read that I could use VirtualBox for both Windows and OSX platforms and put the installers onto the USB drives. (Given that information, I decided that someone coming in with a Linux-only laptop was an edge case that I wasn't going to support.)

Lesson 1 - admin rights
In testing the VirtualBox installer on a few different platforms as users with a few different rights, I found the following: In general, users with "standard privileges" (both Mac and Windows 7) could not install VirtualBox. It appeared that anyone who could generally install applications could install VirtualBox, and I decided that this was another edge case I was not going to support.

(side note: I suspected that some people would not arrive with computers as well. That makes 3 edge cases I've counted so far that would prevent successful hands-on learning. Knowing that edge cases where people would be unable to get this configuration up and going would exist, I decided early that in those few cases, I would just ask that they go and pair with someone who had a laptop with them that was able to get running successfully. My goal was not to waste time working through configuration issues. Also, since each attendee was getting a USB stick with the whole set up, I felt confident that even those without laptops weren't missing anything.)

Once I had decided on that environment, I took to creating the VM I wanted with each piece of what was needed to run Selenium through FitNesse. Each step along the way, I tested what I had on a few different computers -- a macbook pro, a Windows7 desktop machine and a Netbook (least powerful of the three). After only a few tries, I came quickly to ...

Lesson 2 - running from usb is SLOW
This was most evident on the Netbook, but each time we ran a version of the VM while the VM was living on the USB stick, it was dog slow! On the Netbook, it was basically unusable, and that was unacceptable. When I got frustrated enough, I decided that I was going to make sure that each attendee copied the VM to their local machine. Adding this step was negligibly more risky, but the benefit far outweighed that risk.

In some ways, I got lucky
With only 20 people at my tutorial, the risk of edge cases was minimized. It was a wonderful group, though, and the size was really great for being able to address individual needs while still guiding the whole group. I did not run into any of the technical edge cases I was worried about (Linux, or non-admin users), though there were a few people without laptops. Working in pairs seemed to be okay for those people, as far as I could tell.

I feel grateful for how smoothly my tutorial went, given how much trouble I have heard about from other presenters over the past couple of years. I loved the group that came to visit, and we had a blast!