Skip to content

Common mistakes tutorial writers make

#1 They start with their own personal background.

Sorry if it hurts your ego, but no one is looking for your tutorials to learn more about you.

I'm a blah from blah and I do blah. I was doing blah because I needed blah and then blah happened and I got stuck. After blahing around for a while, I figured out blah and I thought I'd write down these steps in case they help anyone else"

Just skip it. People aren't here for your background any more than they are when googling for recipes. Overall, keep yourself out of the tutorial as much as possible - the reader should be the main character with you in the background helping out when required.

#2 They include too much context

In order to understand how to use this Python library, you should first understand what Python is. To understand Python, let me just teach you all of programming quick, but to understand that you need to know what a CPU is...

Assume your reader had the same knowledge that you had before you learned the specific thing that the tutorial is about. Don't teach them the basics - they can go through a syllabus for that.

#3 They include too little context

And then just run the foobar command and everything will magically happen in the background.

"Wait what isn't that the opposite of the previous point?"

Yep, and it's the hardest part of tutorial writing. Predicting at which point your reader will get bored (and reigning in the context) and where they will stumble and fall (and providing just a little bit more). As a rule of thumb, never provide context that is two steps removed (context for the context for the subject matter), but it' a grey area and very hard to define. Practice makes perfect.

#4 The tutorial is too short

It's hard to say something meaningful in less than around 1500-2000 words. If you 'run out' of things to say at < 1000 words, it's likely that you need to either a) make the project a bit more complicated or b) explain some of the steps in more detail.

#5 They provide information that is accurate but only useful if the reader already understands it

Often once a writer has done enough research to understand a topic, they provide a very terse (correct) explanation, but one which they would initially have found confusing without the previous research. You should constantly be aware of and fight the 'curse of knowledge' - try to provide the resource that you would have wanted without your current knowledge.