An open letter to “beginner” tutorial writers

First and foremost I want to say a heartfelt thank you! Without you I would probably be asking people if they’d like fries with their burger. I am a freelance web developer, I am also completely self taught. I started way before Stack Overflow was a thing and YouTube was in its infancy and offered 320x240 cat videos for the most part, so I read physical books.

Over time though the internet has blossomed, bandwidth has increased to the point where YouTube is offering 4k video, and in that time there has been a huge increase in online learning resources. The first large web application I built was written using the Codeigniter framework, something I’d never worked with before, so I went searching, found a great series on NetTuts by Jeffery Way and away I went!

So, you people that dedicate your time to teaching are great, and you’ve helped me build my career. So for that, thank you.

But! A lot of you creating “beginner” tutorials aren’t doing it right. Bold statement right? Bold, yet true. Now I’m not suggesting that this is easy, teaching could be one of the hardest jobs anyone can do, I’m horrible at relating my knowledge in an understandable manner. That being said if you’re going to label your tutorial as “beginner” then you should be making sure it’s actually at a beginner level!

Things that defeat the “beginner” label

Prior Knowledge?

Does your tutorial require prior knowledge? A React Beginner Tutorial probably assumes some Javascript knowledge right? Don’t assume! If what you’re teaching requires some sort of base knowledge state that clearly at the beginning, better would be to offer resources that the viewer can use to gain that knowledge if they don’t have it already.

Pseudocode

Just don’t. Beginners don’t need to see code that doesn’t work with a “do something like this” appended. If you feel you have to use pseudocode only do it prior to actually fleshing out a function with real working code and make it clear what you’re doing.

Do it like this but…

“You create the function like this, but you should put it in its own separate file.” Don’t do this. Don’t ever assume that a user knows how to do something that you know how to do. If you’re teaching a beginner, make zero assumptions of their knowledge. Even if they have prior knowledge do not show code that isn’t how it should be in the finished product.

Type all this stuff!

This is the equivalent of giving a man a fish in my opinion. Your tutorial will tell them how to create a todo list, or a Hello World, but they’ll never move past that. Webpack is one of my favourites for this issue. I have seen a ton of tutorials that show you what your webpack.config.js file should look like. I’ve seen maybe 3 that tell me WHY it should look like that. What each section is doing, how to modify it if necessary. Teach them HOW to fish.

Teaching is hard

Teaching is hard, relating knowledge we already have to people that have less is a difficult thing to do. We often think “this part is easy, no one needs that explained”. The problem is you don’t know what your viewer knows and what is trivial to you may not be trivial to them. Don’t assume. Explain everything, literally everything. If you aren’t prepared to do that then I’d suggest not using the “beginner” label on your tutorials. Please, by all means keep making tutorials, keep passing on your knowledge because that is a noble thing to do and we are all very appreciative of your efforts! Just don’t try to pass off an intermediate tutorial as one for beginners.

Sincerely,
Signed someone that owes you for his career!