We're on Facebook

The click-along demo

The problem

When you write software for a living, you live and die by the demo. People ask you what your stuff does, and you show them. After a while, you get good at it (usually), but that's not a very scalable model. There's only one of you, and, try as you may, it takes a long time to make more of you.

The obvious solution is to record a video of you doing the demo. That's a start, but it's got a number of problems, including:

It's not really the same as seeing a "live" demo, with actual software actually executing right before your eyes

Unless you record in 1080i (and even then), it's often difficult to record a realistic app and keep it readable

Timing is always a problem. Some people are faster than others. Often they want to stop and fiddle with the demo. You can do that in a live demo, but not in a video

If a video is not the ideal solution, another option is to give people the software, and let them run it for themselves. That may work fine for some things, but if your software is complex, or innovative, or unusual, that may not be an attractive option. People may get lost, or they may have no idea what to do in the software. It's just not the same as a live demo where you can point at specific areas of the screen.

The solution

I wanted to have a demo allowing people interactive access to a demo app, but also with a guiding hand explaining what the demo does, how to use it, and how it works.

But I was frustrated by the fact that I couldn't point things out in the app. Then it occurred to me that, actually, I could. The major video players (at least YouTube and Vimeo) have Javascript API's that can keep you informed of the video's progress. It's fairly easy, based on that, to use a bit of Javascript and jQuery to highlight specific portions of the app at specific times in the video.

So I took our standard demo app, slapped a video player next to it, and added a bit of code to connect the two.

The demo is available live, I'd recommend you take a look at it, the rest of this article will make a lot more sense if you do.

What it took

It took me many hours to get the videos right. I thought it would be easier to break up the demo into short segments (each one is a minute or less), but then I quickly realized that continuity was a problem. If I change shirts, or if my hair looks different, or if the light changes, that's going to look funny, so I had to record all eight segments in one sitting whenever I wanted to rework something.

I was really excited about all the options that jQuery and jQuery UI offer to highlight things in an HTML page. Color changes! Shaking! Blinking! But after playing with all these, I came to the conclusion that a simple red outline, blinked twice, was the cleanest (and least annoying) way to go. Perhaps someone with more artistic sense can come up with a better idea?

It took me a fair amount of work to get the Vimeo API figured out. I started with the Flash API, which is poorly documented, and ended up switching to the universal embed code API, which has better examples.

I had to deal with the fact that users have complete access to the app, and therefore can mess things up while I'm talking. They can delete or modify things that I want to point out later. I dealt with this by programmatically reloading the sample data from scratch at the start of the segments that expect that sample data. That way, users can mess around with the app to their heart's content, and I can throw away their changes when I need to. Users can still mess things up if they really want to, but it's a lot less likely this way.

It was relatively easy to get this working reliably in all major browsers (thanks in part to jQuery and jQuery UI).

It also took a fair amount of work to get the videos to chain correctly and reliably. For some videos, I even ran into what seems to be a bug in the Vimeo player, namely that it sometimes doesn't completely finish a video, and therefore never fires the finish event. That problem disappeared once I re-recorded the videos, but that was a puzzling one.

Finally, getting all the events to fire correctly took some work. You can't access the video player before it's loaded. Once it's loaded, you can't really do anything with it until it's ready. The order that worked in this case was:

Event

What gets called

What it does

HTML document loads

jQuery's ready() handler

Register ready listener on Vimeo player

Vimeo player is ready

ready listener is notified

Register listeners for playProgress and finish

Vimeo player is playing

playProgress listener is notified even 0.5 sec or so

Take various actions such highlighting parts of the app, reloading data, etc...

Vimeo player finishes video

finish listener is notified

Hide the current video, show the next one and register ready listener

Vimeo player is ready

ready listener is notified

Register listeners for playProgress and finish

etc...

If you're interested in the gory details, take a look at the code for the demo, it's about 240 lines of Javascript (hint: it's all in demo.js). I'm a long way from being a Javascript god, so it should be understandable by anyone.

Deploying a live demo

Having a demo that people can download is good, but having a live demo just a click away is clearly better. But live demos are always fraught with peril: how will they scale? And how do we prevent people from messing up the data in the database?

The data problem was relatively easy: I modified the demo (which uses HSQLDB - a wonderful little piece of technology) so that every HTTP session would create its own in-memory database, and load it with the sample data set. This of course requires some cleanup, so whenever a session times out, there is a bit of code that shuts down the corresponding database.

Scalability is a different matter. So far we haven't had any trouble, even though the app is running on just two CloudFoundry instances. Obviously the demo itself is not computationally demanding, so the biggest limitation is memory, since each session gets its own private HSQL database. Our tests seem to indicate that each user consumes about 3-4MB of memory, so we should be able to handle about 200 concurrent users in this setup. Perhaps not enough if we get Slashdotted, but good enough most of the time.

Conclusion

Overall, I think this is a very effective way to do a demo. It does take a fair amount of time to put together, but all good demos do.

Having learned all this, I will definitely use this scheme again. It's still not as good as a live in-person demo, obviously, but it's the closest thing I've come up with so far.