The Inverted Pyramid & other Tips on Making Demos

Wiretap’s demo was fantastic. How’d you make it?”

I was pleasantly surprised to get asked this after releasing Wiretap's first demo video. (Embedded below.)

Good demos are hard.

It’s hard not to get lost in features and technical details. It’s hard to give enough context, but not too much. It’s hard to keep a good pace.

I was really afraid of falling into these traps. Wiretap is an HTTP debugger for mobile and web apps integrating with REST APIs. By default, these are the ingredients of a snoozer video.

Here’s how Wiretap’s demo avoided putting (most) people to sleep and some other fun, behind-the-scenes details.

Trust the ole Inverted Pyramid

Put your most important messages in the beginning. It’s all most people will see.

If someone stops watching after 30 seconds, will they know what they need to know?

News writers popularized the idea of an Inverted Pyramid, or, “Bottom Line Up Front”. The idea is readers should be able to leave a story halfway through and have a good enough understanding of it.

  • Who is this product for?
  • Why does it exist?
  • What does it do?
  • How is it used?
  • When is it useful?

The intro to Wiretap’s demo was something I struggled with. Luckily I got some good feedback on the first take from a friend. More on that in the next section.

In the body of a demo: tell a story.

Walk through scenarios that motivate features. Don’t give a feature tour. Reuse the scenarios you came up with to guide your app’s design and implementation. Heck, maybe even copy them straight from your BDD tests, if that’s your bag.

Don’t expect someone to watch your whole demo, but give them reasons to.

Show Friends, Act on Feedback

After hacking on a project for a while it’s really hard to describe it in a demo context-free.

You need fresh eyes.

Show someone who could be a user of your product but doesn’t know anything about it yet. Take action on their feedback.

The feedback I got on the first version of my demo was:

“The intro was missing the why? Why did you build this? Why is it useful?”

He was right.

(You can watch the original with password 'wiretap'.)

I jumped straight into using the product. So I scratched it, recorded new audio, and rearranged the video clips to match. It wasn’t much work and the improvement was substantial. (It could be better yet: the current intro takes 50 seconds. Tsk, tsk.)

Use Bargain Tools that are Easy

Great recording software doesn’t make a great demo, but it can save you a lot of time. Since folks are always curious about tooling, here’s what I used.

Video Capture - QuickTime / iShowU HD - Yep, the QuickTime Player installed on every OSX can make screen recordings. Just go to File > New Screen Recording. You can record the screen or a specific bounded rectangle. It’s a little clunky, though, and lacks some nice features in commercial software like scaling and a better workflow. I’ve had an iShowU HD license ($30 and worth it) for a few years and used it for the Wiretap demo.

Audio Recording - Audacity - Awesome, free, open-source software for recording a narration track. This was the first time I wrote a script for a demo and recorded the video and audio independently. It allowed me to crop out places where I misspoke or had long pauses. This helped the pace of the demo. The downside was that the edits and scripting were noticeable at times, but it was good enough.

Post-production - iMovie - iMovie makes chopping up screen recordings and aligning them with an audio track easy. With software demos you can speed-up and slow-down screen captures to align events with the narration. I abused this freedom. In iMovie just go to ‘Clip Adjustments’, look for the speed section, convert the video, and enter the desired duration of your clip.

Have Fun, Keep it Light

Sprinkling in some spice won’t take away from your meat and potatoes.

With Wiretap I wanted to walk through a complete Mobile App + Server-side API + 3rd Party API scenario. Doing something that was the “AirBnB of ____” seemed pretty obvious and my dog was laying under my desk looking guilty at the time so I ran with “ShameKennelRnR”. I dropped in a few little easter eggs, as well.

Be excited to show off what you’ve been hacking on and have fun with it.

Shameless plug: Do you hack on REST API integrations or implementations? Wiretap is entering private beta soon. I’d love your help testing it. Sign-up over on Wiretap's demo page.