Head-desk-head-desk…..

Do we ask too much of people who write tutorials?

I have a common problem, I’m not that bright most of the time. Most people aren’t. Most people don’t have to be because we can all Google things and that’s as bright as we need to be in the modern age and I’m mostly OK with that…

Until I really think about it and then I despair for the future.

I digress.

Anything in the world that you don’t know how to do you can find out from the internet. Google and YouTube are your go to fonts of human knowledge, teeming with the collective wisdom of millions of people who by and large know their shit. Tutorials are everywhere. The online learning industry was apparently worth $107 Billion in 2015 and that isn’t including the free stuff so you can triple that for a start. It’s huge and there’s the problem.

How do you find the one you want? The one that’s at the level you need? The one that actually solves your problem and doesn’t make you spend 15 minutes reading to find out it’s about something else?
I spend half of my day sometimes researching how to do a new thing online, a new language, framework, pointless time sucking workflow trend or whatever and the tutorials are shocking. I’m mean that. Utter rubbish designed to keep you reading for 5 pages worth of adverts whilst missing out the crucial part of whatever it’s trying to teach you. I’ve fallen for it before. Many times.

The problem is assumed knowledge.

The tutorial writer assumes, subconsciously I hope because otherwise they’re an arsehole, that we all know the basics of what we’re looking up, or worse, that we all know what they know already. You see it all the time in programming tutorials…

“Simply alter the SASS file and it will all be compiled by unicorns into perfect reusable code and your peers will deify you”

Neglecting to mention that it will compile into nothing because although the writer carefully took you through all of the command line steps to compile SASS they didn’t mention the part about having Ruby installed first, so it won’t work and you won’t know why.
Took me 27 different tutorials to find out that little snippet of information. 27. Work that out in billable hours and then add the cost of a keyboard.

I was going to write a similar tale about Node.js and NPM and Grunt but read those two links there and you’ll see why I didn’t want to smash another keyboard.

It’s not always hard to fix either. Take Bower for example. Line 3 of the install instructions state “Bower requires node, npm and git”. This is good. If it added “installed in that order” it would be better because some poor beginner is going to come along and not realise that the order is important, lose half their day, their hair, and their will to learn and possibly to live.

So a plea to the writers of these things:

Remember that not everyone is already an expert, if they knew as much as you they wouldn’t need the tutorial.

If you’re writing for a beginner write from the beginning. If something needs prior knowledge then point that out at the start, even a link to a more basic piece would be good.

Please don’t make us get to the end before we figure out there were three steps before you started, remember it’s you we’re calling names at that point.

Don’t use the phrase “simply blahblablah whatever it is” you’re assuming prior knowledge again and that’s bad.

Give it to your kids to read, if they can can get SASS up and running from scratch after reading what you have written then the rest of us should be cool. Unless your kid is a genius, in which case use another kid who isn’t.

You’re all writers and I’m not, so I’m going to assume you’re getting my point and leave it here with my thanks for the sterling work that most tutorial writers do. Keep it up we all need to learn stuff but I swear if this goes missing in Github again I’m coming for all of you I swear…………..

Leave a Reply

Your email address will not be published. Required fields are marked *