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.
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…
- 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
- 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
- …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!
- 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.
- Even if it’s just
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!