Todd's Guide to Creating Video Tutorials

Wait — do I really have to write a script?

I mean, I’m not gonna tell you how to live your life, but I will say that nearly all of the video content I create is scripted beforehand. Yes, there are some people out there who are talented enough that they can talk while coding and still sound natural and entertaining — Jeff Delaney of Fireship fame says that he never writes out scripts beforehand — but I am not one of those people. And, frankly, you might not be either — it can be really difficult to code and narrate at the same time! It’s like rubbing your belly with one hand, and trimming your cat’s nails with the other.

To be clear, there is a place for unscripted, “I’m just going to narrate while I code” types of videos. I’ve made those in the past too, but I think when people are looking for video tutorials, they’re looking for something with some tighter pacing so they can get the job done and move on with their lives. And if you can get that tighter pacing by knowing exactly what you’re going to say beforehand, it’s worth the effort.

Also — and maybe this doesn’t apply to you — but I frequently work for companies where I have to be careful what I say. People were looking to sue Google all the time! And with Plaid being so deeply intertwined with people’s finances, I can’t say something off-the-cuff that might be misconstrued. Particularly if that off-the-cuff remark is preserved in perpetuity on YouTube.

So with all that in mind I would recommend writing out a script where you plan out everything you’re going to say.

▼ A hybrid approach?

For my last video, I tried more of a hybrid approach where I wrote down ahead of time everything I planned to say on camera (or over slides), but then just had detailed outlines for the actual screencast portions. It worked okay! I was able to save some time on the scripting portion of the video (particularly since another engineer had reviewed my code already).

But in the end, this didn’t end up being as much of a time saver as I had hoped.

The issue was that, while I saved time when writing my script, I ended up spending more time than usual fixing things in editing — my narration had a lot more “ums” and “y’knows” that I tried to remove, and my code had more typos. Both of which were a side effect of my trying to do two things at once and splitting my concentration. I also had to spend a lot more time than usual making the captions track for my video, since I didn’t have a full script to start with.

And in the end, while the video game out fine, I feel like the pacing took a bit of a hit — it didn’t feel quite as tight as my other videos. These days, that’s not a huge deal — people can always adjust the speed of your video to their liking — but it’s something that bothered me.

The Script Template

I like to write scripts using Google Docs in a two column format — this is a format we started using at Google and it’s pretty nice. In fact, here’s a template you can use.

You’ll notice the script begins with a little header where I force you to write out the answers to a bunch of the questions I asked in part 1. This is both for your benefit, and also for the benefit of your readers. It’s also a good place to call out any topics you maybe wanted to cover, but have to be deferred for future videos, so your reviewers don’t ask about them.

On the left hand column, I write out the words exactly as I would say them on camera. On the right hand side, I put rough guidelines for what’s going to be on screen — maybe code snippets, or mock-ups of your keynote visuals. These visual guidelines don’t need to be perfect — just enough that a reviewer has a general idea of what’s going on. (Or you can remember what you wanted to put in there)

Within your script, make sure it’s easy to identify which sections correspond to which types of visuals (on-camera portions, screencast portions, etc.). This will both help your reviewers, as well as make sure you don’t accidentally miss a section when you’re doing your recording later.

If there are any parts where you think you’re going to want to show yourself on camera (more on that in step 7), I recommend making those parts of your script obvious. Give ‘em a green background or something.

I also like to put the word “SCREENCAST” and “BACK TO SLIDES” in big capital letters before and after each screencasting section so I remember when I’m switching to a screencast (vs slides or on-camera work)

Okay, fine, but what do I actually write?

The process for writing a script could be a full blog series by itself. But here’s a few important tips when it comes to script writing…

Overall Structure

• Introductions are hard! If you’re looking for a catchy introduction, try framing your video in terms of “Describing the problem, and then proposing the video as a solution”.
  • For example, “Sometimes when you’re building an app, you’re going to need do X. Well for that, you can use Y. And I’m going to show you how on today’s episode of …”
  • Alternatively, you can start by showing them the final product you’re going to build.
  • In both of these examples, you’ve framed the problem, created a little bit of tension to draw the user in (“Wait — how do I build X?”), and then let them know that all their questions will be answered in the video.
    • And that’s all the narrative tension you need!
• You’ll notice a lot of my videos follow a pattern of, “Let’s explain the concept behind the next step” followed by “Okay, now let’s implement the stuff I was just talking about.” That way people aren’t blindly copy-and-pasting code without really knowing what they’re doing.
  • Sometimes you can do this in the opposite order if you realize that the explanation would be a lot easier to understand if the viewer could follow along with some sample code. But either way, you want to alternate between explanation and code frequently.
• As you’re writing this script, you might realize there’s another topic that a developer needs to know about as a prerequisite. If that’s the case, you might want to pause on this video and work on the prerequisite video first.
  • For instance, a lot of Plaid products require knowing about webhooks. Rather than try to cram a full tutorial about webhooks into my other videos (and risk boring developers who already understand what webhooks are), I made this a separate video that I could refer developers to if they needed it.
• You will probably realize that there are entire other topics that you could cover, but can’t for the sake of brevity. It’s best to list those near the top of the script. Both for reviewers who might ask about it, but also as a reminder to yourself when you’re looking for ideas for future videos.
• Sometimes you’ll realize an entire section is unnecessary and can be cut. This is one of the hardest parts of script writing — cutting out good material that doesn’t serve the main point of the video.
  • One trick that helps me is taking the material that’s going to be cut and just moving it to the bottom of the document. That way, it’s not gone forever, so I feel better about leaving it out.
  • Also, I have that material to refer back to in case I ever make a follow-up video on the topic.
• Wondering how long your script is going to be when you turn it into a video? I’ve found that “one page = one minute” is a pretty good guideline, if you’re using the two-column format.

Tone and Language

• Humor is risky! And this is coming from somebody who puts a lot of humor into their videos. On the one hand, it’s good to be lighthearted! Developers are people just like you and they appreciate a good chuckle…
  • …but too much bad or forced humor can make your video really tough to watch. Cringey humor can bring a video tutorial down much more than good humor can bring it up.
  • Also, remember that developers are watching your video because they have a job to do. They don’t want to sit through “Todd’s comedy routine” to get to the relevant information.
  • So I’d say it’s okay to be funny as long as you’re not going out of your way to do so. If it’s part of the natural flow of your script, fine. But if it feels like you’re spending half a page trying to set up a joke, it’s a good sign that maybe you should cut it.
• Keep your language simple! It’ll sound more natural when you’re reading it out loud (we tend to use fancier words in writing than we do in everyday speech).
  • But also, remember for many of your viewers, English is their second language, so keeping things simple can make it easier for them to understand what you’re saying.
  • As Mark Twain used to say, “Don’t use a five-dollar word when a 50-cent word will do.”
• Remember that there will be visuals on screen, so you might not need to be as detailed in your script as you initially think.
  • That is, instead of saying, “Now, I’m going to the dashboard menu at the top of the screen and click ‘My activity’” you might be able to get away with, “Now, I’ll go up here and click “My activity””
• When I’m making longer tutorials, I use “we” a lot. (“Let’s open this file here and add our new method”). When I’m making the short “x in 3 minutes” video, I use the imperative form, (“In your server code, add this method…”) But that’s not really a hard and fast rule.
• Try to be genuine. If you’re genuinely excited about a feature, it’s okay to sound excited. But if you’re overselling a feature you don’t actually care about, your users will know.
• Ooh, let’s talk about storytelling!

▼ Todd's mini-rant about how storytelling is overrated

The other day, I realized the flapper in my toilet needed to be replaced. Luckily, with the help of an extra flapper, I was able to follow along with this YouTube tutorial and stopped my leaky toilet. It was a short and sweet video that contained everything I needed to replace my toilet flapper. You know what I didn’t need? An overly long anecdote at the beginning of a video about Hilda Homeowner who had toilet problems.

And I think we’ve run across the recipe blogs where you have to scroll through five pages of somebody’s life story just to get to the ingredient list.

Now, let’s be clear; I’m not here to tell you that storytelling is pointless. Storytelling is great when you need to make a compelling argument. Every politician knows you can persuade more voters by telling them a inspirational / heart-wrenching story about a working-class hero instead of quoting statistics. In fact, did you notice that I started this section about how storytelling is overrated by telling you a story? (Whoa!)

My point is more that your LinkedIn feed is full of people with roles like “Chief Storyteller” who, at this very moment, are writing one-paragraph-per-sentence posts about the power of storytelling. And it gets to the point where you might think that all of your videos will be pointless without a long story at the beginning — I know I was guilty of that at one point. So I’m here to counteract some of that.

When you’re making a video, you need to ask yourself — am I making a inspirational video? Do I need to get my viewers hooked, and persuade them how fantastic my technology is? Or do they already know what they want to accomplish, and I’m helping people perform the engineering equivalent of replacing their toilet flapper?

Because if it’s the latter, your “story” can be as simple as “Once upon a time you didn’t know how to implement this thing. And now you do.”

With all that said, here’s two lessons from storytelling that you can put into a script. Even if it’s a toilet-flapper video.

First, there is value in making an example more concrete — as long as it doesn’t complicate things too much. When I was making Firebase videos, I would constantly refer back to a hypothetical restaurant review app. It made it easier for viewers to understand what kinds of schema you might want in your database, as well as prime them with questions they might want answered.

Second, as I mentioned earlier, “Hey! Here’s a problem! Let’s find out the solution on today’s video!” is a great narrative hook, and still my favorite way of introducing a video. And it takes all of about 20 seconds.

Code

• It’s impossible to make video content that covers every client and every server platform. So I usually prefer to make content that uses vanilla JavaScript on the frontend and Node.js on the backend; my reasoning being that these are common enough technologies that even if you’re working in an entirely different setup, you can still probably follow along and get a sample app up and running. (Not everybody has a copy of Xcode, but they all have a browser!)
• I will sometimes use a framework like React if I think it will end up with less code, but you need to be careful here. Every technology you add risks isolating an additional group of people who might not be able to follow your video because they can’t understand it.
  • Also, every technology you add increases the chance that your user isn’t able to get their app running because of some installation problem that you didn’t think about.
• If you’re making a “code along with me” guide, make sure that the developer can run their code, and they see visible progress throughout the entire video.
  • Even if it’s just console.loging some stuff, or encountering new and exciting error messages, you want developers to see some visible change between the current step and a minute ago.
  • Also, you want developers to “fail fast” if something goes wrong, so they can immediately figure out where they went off track. So make sure you’re constantly having them add and test small bits of code instead of, like, waiting 20 minutes before you compile and run.

Once you’ve taken the time to write out your script, go back and read it out loud (Yes — really out loud. Not under your breath!) to your partner, young child, cat, or reflection in the mirror. Often, phrases that seem perfectly reasonable in writing sound clunky when you say them out loud.

Getting Your Script Reviewed

When the first draft of your script is written, send it off to be reviewed. This should be by at least one subject matter expert — an engineer or the PM on the product you’re talking about, for instance — and somebody who isn’t necessarily an expert, to ensure your script is still understandable to newbies.

In the past, I’ve tried to get people to officially sign off on scripts, with mixed success; Google had a strong culture of people signing off on Google documents — Plaid doesn’t. These days, as long as my reviewers have had time to add comments (and I’ve addressed those comments), I consider that good enough.

When it comes to feedback, remember that you don’t need to accept everybody’s feedback, but you should at least take the time to understand why they’re giving you the feedback that they are.

It can sometimes take a while for a script to be reviewed, so while you’re waiting for that, feel free to move on to the next step!

Part 4: Do some more prep work!