Skip to content
Posted on:November 6, 2023 at 04:06 PM

Todd's Guide to Creating Video Tutorials

Part 3: Write a script

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).

Sample hybrid script

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.

Sample script template

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)

Screencast and on-camera portions of the script

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

 What about bugs or issues with our product?

What happens if there’s a known bug in your product, or, at the very least, a thing that’s just kind of a pain in the butt to deal with? Should you call attention to it? Ignore it? Pretend like it’s not a problem?

My philosophy is if there is a legitimate problem that most developers are going to run into, I’d rather have them know about it now, while they’re watching my video and I can tell them about workarounds (or at least commiserate with them) instead of days later when they’re struggling on their own, and they end up wiring angry frustrated rants on Hacker News / Reddit.

So if something is pain in the butt to implement, or doesn’t work as well as it should, it’s okay to say that! I know can sometimes be hard — particularly if you’re in the marketing org, or you need to get your script reviewed by the PM of the product * Surprisingly, PMs don't always like it when you describe their product as a pain in the butt — but it’ll grant you some credibility, and your viewers won’t think they’re missing some obvious solution.

Tone and Language

 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.

Twitter joke about recipes

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.

Twitter joke about recipes

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.”

Twitter joke about recipes

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.


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!

Hello world!