Recently I had to produce a demo video as part of a tool paper submission. Here are some notes I gathered in the process: they might be useful to my future self or to other wannabe videomakers.

Caveat emptor

My experience amounts to the one demo video I produced and a few (say, between 5 and 10) ones I have seen in the past few weeks. So, take this post with a grain of salt.

Also, these suggestions are targeted to CLI videos. I think some of these suggestions may also apply to a GUI demo, but I am certain that demonstrating GUIs presents additional layers of complexity which I never had to deal with, luckily.

What a demo is not

A demo is not a pitch: there is a fine line between demonstrating the capabilities of a tool and trying to sell it. A tool demo should not be flashy or bombastic. If your tool is groundbreaking, a plain presentation will not hide it. Just look at The mother of all demos, and notice how doug Englebart never tries to sell the features he demonstrates. Even his voice is always composed and soothing, even though he was presenting what amounted to sci-fi stuff back in the late Sixties.

A demo is not a live coding session, either. Live coding videos may be very interesting in their own right. Being improvised by nature, they can provide a unique standpoint to understand development/architectural choices because you can actually see the process leading to these choices. For instance, take a look at the Antirez Youtube channel. On the other hand, you cannot improvise a demo video. I believe these videos should have a more-or-less fixed structure. Also, typically they are required to be shorter than a given length (say, 10 minutes). So, you should do a bit of planning.

Demo structure

In my opinion, a demo should roughly consist of:

  1. An overview of the problem your tool aims at solving;

  2. A basic example of said problem;

  3. A first invocation of the tool on the basic example, with as few arguments/options as possible;

  4. A discussion of the tool output, showing that it does solve the basic example;

  5. Additional invocations showing interesting arguments/options, and discussing the respective outputs. I believe it is best to use the same basic example for all invocations, but you may introduce slight variations (in that case, reserve some time to explain these variations);

  6. Final information about the tool (availability, licensing, etc.)

Outline/TLDR

What I suggest is:

  1. Write down a general structure of the video;

  2. Practice all the commands you need to enter on the command line;

  3. Make a text file with (more or less) everything you want to say in your voiceover;

  4. Use a terminal recording tool to record your commands and their outputs, without any voiceover;

  5. Record your screen as you play back the recorded terminal session and do the voiceover.

Practicing commands

Demos need to effectively show the features of the tool. Fumbling on the command line is not the best course of action toward that goal.

At the same time, I think that pasting commands, or recalling them from terminal history, is not as effective as typing them in. Typing gives you a chance to explain the command on the fly. This is very important when your command involves multiple arguments and flags. (This makes me think about Powerpoint-driven lectures. On average, they are not as effective as those where the teacher actually writes on a whiteboard, are they?)

Of course, if at some point of the demo you just need to append arguments to a previous command, then you should use the terminal history rather than typing the whole command all over again.

Writing down the voiceover

Again, it is hard to do a good voiceover without writing down more or less everything you are going to say. This is especially true for non-native English speakers. Writing down a script helps you realize if you know how to pronounce uncommon words, where to pause, and so on. It also gives you a feeling of how long the video is going to be, and what parts you might want to trim down.

Recording the terminal

Next, perform your demo on a terminal and record it with a tool like asciinema. Do not use a screen recorder at this stage. Personally, I set up a full-screen terminal window with a big font size (18pt at least) and fire up a tmux session with a vertically-split pane. The left pane is where I type commands, while the right pane contains a pager (i.e. less) with my voiceover text file.

  • A big font size means that, in the end, you can export your demo at low resolutions (576p or even 480p) and your commands will still be readable.

  • The right pane acts as a teleprompter for you and as subtitles for the audience.

  • At this stage, I don’t worry about timing. I scroll down the right pane at a slow but constant speed. When it is time to launch the first command, I switch to the left pane and type it in. When the command terminates, I switch back to the right pane and resume scrolling. And so on and so forth.

Adding the voiceover

Finally. Just fire up a screen recorder with microphone capture, play back the recorded terminal session, and describe what you are doing. Pause/resume the playback so that you have time to describe everything that is happening on the screen without rushing.

  • I did the screen recording/voiceover part with QuickTime and iMovie 10, but I do not recommend the latter. It only exports to MOV and will force a 16:9 format by either cropping the recording (!!!) or adding ugly black bars, and the exported videos will be blurry. In the end I managed to undo most of the damage (i.e. remove the black bars and sharpen the video) thanks to Handbrake, but I recommend looking for less painful alternatives, or at least checking if newer versions of iMovies have improved on these issues.
  • Always downmix your voiceover to mono. I see no reason why you should split your microphone (which is most likely mono) across a stereo audio track. (Of course, if you’re demoing an audio processor or similar stuff, you might want stereophonic audio…)

Sharing the video

If the video is targeted at reviewers only, I believe that hosting it on cloud storage is better than a relying on video sharing services such as YouTube or Vimeo, which might add unwanted compression to your video. On the other hand, these same services can typically handle higher traffic and hosted video are somewhat “more permanent” than those on cloud storage. Thus, they may be the best choice if you must provide a video link in the published version of your paper.

Good luck with your videos :)