How To Tell A Story With Code

August 09, 2012
Written by

Twilio Bug Logo

Photo by kodomut
Whether you are in front of a packed room of hackers, a huddled group on a trade show floor or a sweaty basement filled with gutter punks, every audience just wants you to tell them a story.  From sprint demos to superhero flicks, telling a good story is the surest way to captivate a human being’s attention, spark imagination and compel absorption of your ideas.

Narrative is this crazy itch we all want scratched – if you think back to the last speech, song or standup routine that really grabbed your attention, chances are good that it told a story.  This very human craving is something we try to feed on our developer evangelism team here at Twilio.  But, I’ll be the first to admit, constructing a narrative out of code is damn tough.

As a developer myself, I want the presentations I attend to be full pragmatic utility and technical detail.   If you’re telling a story built around technical concepts, the narrative can’t be ornamental or bolted on.  Pretty language or fairy tale use cases doesn’t impress hackers – the value of their time is too immense to waste with extraneous metaphor.

Further, Twilio’s products present a difficult storytelling challenge.  The broad theme of powering communication binds them all, but threading together Twilio Voice, SMS and Client into a coherent tale that will capture a busy coder’s attention is a problem whose solution is solidly non-obvious.  Ringing your phone, sending a text message and talking into your browser are very different human experiences that live mostly in isolation.  Can you immediately think of one contiguous, compelling scenario that would loop in all three?

Finally, the pure act of telling the story with code is super hard.  Technical audiences – to my undying gratitude – are very discriminating.  Some joker in a red jacket can’t come along and hack out a mommy class and a daddy argument instantiating a little baby object together and expect to earn a developer’s respect.  The code written in this story needs to be non-trivial and instructive, do something the developer can’t just squeeze out in five minutes looking at the documentation, and – above all – work.

Factor in all three of these challenges and storytelling through programming starts to look pretty tough.

Constructing A Narrative Out Of Code

But telling that story is our job as developer evangelists and doing that job well is your expectation as our customer.  And like all the difficult problems we work on at Twilio, the solution involves breaking it down to its constituent components and solving each individually.  In this case, we need to figure out a framework around which we can build a narrative, find a theme that is compelling, cut some code that works and put that all into one story that would be worth telling.

In broad strokes, a story is a coherent narrative with a beginning, a middle and an end.  While extremely basic, such a framework quickly starts to make the solution easier to find.  For a technical presentation, a beginning could be a problem statement – a description of some issue that resonates with the audience.  The middle could be writing some simple solutions to address the discrete parts of the problem.  Finally, the satisfying conclusion could be stringing that code together into software that works.

The Karaoke Case Study

Such a framework makes the narrative coherent, but leaving it at the paragraph above would be a serious snoozefest – our story needs to be interesting!  No matter how many lolcats I sneak into the deck, no one is going to leave happy if my beginning, middle and end is boring.

Using the narrative framework we described above, everything hinges on the problem statement.  If the problem statement captures the audience’s attention, the solution is likely to sustain it.  But what is a problem that is likely to resonate with a broad technical audience and be solved by telephones, browsers and SMS?

In my own experience, the problem statements that grip my attention are the ones with absurd combinations of high-powered technology with completely unrelated problems.  Jet powered beer coolers, automatic grapefruit segmenters made of Legos, Arduino ping pong cannons – I love them all.  Capturing that kind of audacious hacker spirit in our problem statement is sure to be compelling.

A few months ago, such a problem statement came to mind when looking at the Twilio logo.  Our tagline is “cloud communications” – what if we used cloud technology to solve an unexpected problem akin to using a jet engine to supercool Guiness?

What if we used the cloud to sing karaoke?

A Cloud-Powered Story

Building a karaoke machine in the cloud is a catchy theme and perfect for our narrative framework as we have four different pieces to build: the microphone, the sound system, the music and the lyrics.  Further, they conveniently align with the building blocks we’re trying to make a story out of – Twilio Voice, SMS and Client.  Now we just need to cut some Python that’ll do it.

For the microphone, we can use the phone in the pocket of an intrepid audience member by hacking out a quick TwiML Voice app that puts the audience member in a Conference.

For the sound system, we can use the speakers on my presentation laptop by dialing into the same Conference using Twilio Client and a browser.

The music we can deliver into the Conference by scripting a REST API request to call into the same number as the audience member and execute a verb.

Finally, the lyrics for the song we can send via SMS line-by-line to the singer’s phone from a text file.

String it all together with a few bad jokes and we suddenly start to have a quality story we can tell.   Not only do we use all three building blocks we wanted to start with, but we also use them fully by demonstrating inbound and outbound Twilio features. With the snippets of code above we have a solid middle to our story that builds to a full karaoke machine – a suitable conclusion for our code-powered narrative.

Making It Work

Now, all that is left is to tell that story.  Here’s an attempt at such I gave recently at Philly Emerging Tech.

ETE 2012 – Rob Spectre – How to Build a Cloud-Powered Karaoke Machine from Chariot Solutions on Vimeo.

The code for the presentation is up on GitHub, as well as the slides from the deck.

Storytelling is a crucial skill for all public speakers – we who ply our trade in tech shouldn’t consider ourselves excluded.   A strong narrative is hard to ignore and whether you are slinging slides, bullet points or lines of code, every presentation would do well from having one.

Just like this blog post, if you build your presentation with a strong beginning, middle and end, a compelling theme, and make them work together, you will capture your audience’s attention and – hopefully – their hearts and minds as well.