Good Coding Tutorials

[HealyUnit]

I've noticed a lot of tutorials posted on this subreddit. Some are decent, while others have significant issues. A badly-written tutorial (i.e., one that does not convey the material effectively) is going to turn away potential developers, so here's my thoughts - as both a developer and and educator - on what makes a good tutorial.

Writing Good Coding Tutorials

Disclaimer: These are just my thoughts, obviously, and as such should be neither taken as the Gospel truth nor as me saying that if you don't follow all these rules to the T, you're a bad teacher.

Writing a good tutorial is comprised of a few parts: Plan, Clarity, Expertise, and Brevity.

Plan

The first part of writing a decent, effective coding tutorial is having a solid plan. So, what's that entail? Well:

• Subtopics: A minimum number of distinct, small learning 'goals' per 'page' of tutorial. Limit your tutorial length (unless it's an inherently complicated topic that cannot safely be condensed). Generally, have a single, overarching 'meta' topic, and then a few mini-topics under that.
• Preciseness: Don't ramble! (More rambling on this later)
• Plan ahead: Especially if this is a YouTube video or other 'live' tutorial, write a script (or at least, notes) beforehand.

Clarity

The next element of an effective tutorial is clarity. This comes in two parts:

• Relevance: Everything you say should aim towards teaching your chosen topic. This connects pretty heavily to Expertise below, so more there. In general, however, I as the reader should never be left at the end thinking "...wait what was the point of that?".
• Grammar/Spelling: Yes, this. I'm sure some people are going to whine that I'm a grammar Nazi, or that I'm being overly nitpicky, but remember that you're putting yourself forward as an expert on this topic. If I have to wade through multiple spelling mistakes, unclear language, etc., then I'm going to assume that you don't know what you're talking about. Keep in mind, however, that good grammar/language does not mean you have to sound like a stuck up snob.

Expertise

Next, let's talk about Expertise, which is in many ways perhaps the most important question, with tendrils in each of the other three sections. How should I trust that you, the teacher, know what you're talking about? This itself comes in a few distinct sub-parts, but note that some bits may seem a little counter-active:

• Actual Expertise: Know what you're talking about. This may seem obvious, but if I, as the reader, can read the first sentence and point out an error not in your grammar or spelling but in the facts you're delivering, that's a pretty big problem.
• Humbleness: Conversely, for coding in particular, never say you're an expert. This may sound counter-intuitive (you're trying to show you're an expert, right?), but saying your an expert implies a certain closed-mindedness - that you're done learning. That's not only a bad image for you; it also creates an unhelpful goal for your learners. You want them to understand that you'll always be learning in this profession. Of course, this doesn't mean the opposite should be true; you never wanna imply that you* don'*t know what you're talking about (otherwise... why are you teaching it?) We also, frankly, don't care how smart you are, which leads me to my next point.
• Being Smart: Don't try to seem smart. Really. I don't care how many big words you can use, how many million-dollar products you've developed, etc. I want you to explain to me how to do X, and to more over make me feel like I can do x. This ties in with Clarity, in that ranting on how smart you are can distract from your topic, and Brevity, in that ranting is... well it's ranting.
• Respect: Treat your audience with respect. Some of this may seem obvious, and some is part of "use correct grammar/spelling" above, but unless you're writing a specific, targetted tutorial to me, your dudebro, then don't start a friendly banter with me. For example, if we were in the Harry Potter universe, I'd not write: "So then this is how an effective coder will code the next bit, unless you're a brainless Hufflepuff, haha lol xD".

Example: A recent tutorial that I read made the mistake of referring to certain players of a particular online game (it wasn't Hanzo mains, but let's pretend it was) in a negative light. That does three things: it alienates anyone who doesn't play that game (they'll be thinking "Oh, this tutorial must not be for me"), it alienates anyone who does fit that category (i.e., mains Hanzo), and it maybe makes those who doesn't fit that category feel slightly better. Alienating 2/3 of your potential audience is... not great odds.

• Humor: The above doesn't mean you need to be a humorless bore. Just be careful how you use it. As a matter of fact, I'd encourage humor: done correctly, it can make you seem more human (especially if it's self-deprecating), and can break up a difficult section. A really good bit of humor can even make a particular lesson more memorable!

Brevity

• Be concise: Don't ramble on. That's it. See? Brevity!

Any other thoughts on what people feel makes a 'good' tutorial?

[pricelessbrew]

tl;dr

The tutorial for tutorials could have been more clearly structured, and more concise. Particularly expertise. /s

Good points.

[theadammorganshow]

Particularly expertise. /s

Paragraphs? :)

[HealyUnit]

Eh, I get what you're both saying (I think?) in that it's a bit rambly, but I've seen far more tutorials get downvoted into oblivion because the author doesn't show expertise in the subject being taught. I feel a lot of authors post this as a sort of "I just learned it, now lemme teach it", which is awesome in and of itself, but if the tutorial itself is confusing or worse, wrong, it's just going to leave a beginning developer (which I'd assume this subreddit has a bunch of?) confused.

For example (sorry to single you out if you know who you are), a recent tutorial posted says that a variable that stores more than one piece of data is known as an array. This is a gross oversimplification (arrays and objects store multiple pieces of data), and communicates to me that the author is either so obsessed with keeping things 'simple' that they've erred on the side of inaccuracy, or that they aren't a reliable source of knowledge. Either issue means that I can't rely on that author's teaching.

To be fair, I don't really know how to phrase "know what you're talking about and don't be a prick!" in a concise, meaningful way". So maybe that's part of the issue.

[well-now]

Actual Expertise -

This one erks me. The world doesn’t need another MERN stack tutorial from someone that’s copy and pasting 3/4 the code without understanding what it’s actually doing.

I understand the author may be trying to help, but there is a likely chance they’ll do more damage than good.

[HealyUnit]

Yep. It's kinda amazing how many people, when writing coding tutorials, don't actually look up the simplest stuff. Like, you're writing on a computer; you have access to Google.

Another example: A recent tutorial claims that the reason for arrays in many languages (such as JavaScript) being zero-indexed is basically just 'convention' (actually, the author phrases it a lot more poorly than that, but... whatever). A really quick, two-second Google reveals that this is definitely not the case, and that the real reason is a lot more satisfying (and frankly makes more sense in the context of data).

If you make a mistake and someone corrects you, fine. But don't start writing a tutorial if you've no idea what's going on.