How to Create Tech Tutorials
People often ask me how I write tech tutorials. I’ve given partial answers time and time again, but I wanted to cover it all at once so that you know what I typically put into a tutorial and how you can plan one out.
To date, I’ve written over 60 free tutorials, recorded many free videos, and over 100 videos for my various courses. So I’ve got some experience.
And before you say that “this isn’t for me” — we’ve all got something unique to share so please don’t think you can’t do it, no matter how junior you may be! I started writing tutorials as a way to better understand what I was doing day to day in my job.
Choosing the Topic
I don’t have much of a system for choosing a topic but it typically falls into one of three categories
- “Docendo discimus” (by teaching, we learn) — if I’m learning something new and I want to understand it fully I try to teach it. This makes me go through code line-by-line and explain it.
- I use something, and it helps me — maybe it’s push notifications, maybe it’s Meteor + React Native. If I use something and I think others could also use it, I share that knowledge.
- I’m asked about something. I receive 50+ tech related emails a week. If a question comes up a lot, I write a tutorial about it.
The Code
A tech tutorial is going to, most likely, involve some code. Don’t try to write the code while you’re also writing/recording the tutorial. For me, it just doesn’t work out and ends up in a low-quality pile of 💩.
Write the code first.
Planning the Tutorial
Outlines are everything! My outlines are bare bones and just a simple headline that represents the goal of that section.
If I’m recording a video, I’ll put together a “shot list” which is just a series of shots I want to record. A section will have anywhere from 5 to 15 shots. This helps me record the video in short segments, allowing me to re-record segments when I make mistakes, and edit it all together later on.
I’ll typically form my outline in the following way:
- Take my code example and comment out everything directly related to the concept I’m trying to teach
- Create a repo/branch with the starting point of the code for the tutorial
- Uncomment pieces of code in related segments, making my sections. My goal is that every section can be run on its own.
- Make a repo/branch with the finished code
A note on the starting point: Think about your target audience. What do they already know? Don’t worry about basic setup if you’re targeting an intermediate/advanced audience. Just give them code that works and if they want to know all the details they can read the code over.
Creating the Tutorial
When it’s time to create the tutorial most of the work is done. You just need to describe what you’ve done and piece it all together.
Why did you write the code in this way? What can they expect as a result? What issues might they encounter? How do they fix those problems?
Protip: Avoid rambling/getting off topic. Try to stay focused on the topic you’re teaching. I struggle with this a lot on video, which is why I try to record in a series of short clips.
If you’re recording video: TAKE YOUR TIME. It’s hard. You’re going to make mistakes. Figure out how to make those mistakes low stakes.
Edit the Tutorial
For a while, I didn’t edit my tutorials. When I finished them I wanted to publish them. It works fine but it can cause issues for your audience when things don’t quite line up. A simple restructure of the sentence could clear everything up!
I’ll typically write and edit on different days. I also try to do it at a different time of day so I’m in a different state of mind. I want things to be super clear and make minimal assumptions.
I do this full time and I’m still using Quicktime and iMovie to produce videos. If I’m writing I’ll often write directly in Medium or use Grammarly to ensure my writing is decent.
Share the Tutorial!
The moment you’ve been waiting for! Press “Publish” and share it! Where does your target audience hang out? Is it HackerNews, Twitter, a Facebook Group, Reddit, etc.? Maybe Medium is a good place to post it? This is my weak point, but I’m learning!
So that’s my process. How much time does it take? Well, for a 2 part series on React Native + GraphQL Authentication I spent upwards of 13 hours putting it together.
Holy shit that’s a lot of time! Yeah, it is, but I love doing it and that was a big series (20 minutes reading, 1 hour of video). Your tutorials don’t have to be that long at all. Keep it simple and write something.
I hope you found this little post helpful!
Have more questions about creating tech tutorials? Let me know!
My name is Spencer. I teach people to become full stack mobile developers using React Native, GraphQL, Meteor, and more. If this sounds like something you’re interested in sign up for my email list!
