The Problem with Most Programming Tutorials / Books

Or Why they all suck (and how to improve them)

I can't remember the number of tutorials / books on programming I've had to abandon, because the author jumped to advanced concepts too fast, or tried to teach too many concepts at the same time.

Having worked with beginners and been a beginner to new technologies myself, I have seen many beginners just quit.

Most commonly, I see two types of problems:

• The "Rest of the Owl Problem"
• The "I'm writing to impress Reddit/Hacker News" Problem

The "Rest of the Owl Problem"

There is a whole subreddit dedicated to this. The picture is explains everything:

Many tutorials fall into this trap--they will teach some basic theory or give some toy examples, and then just straight into the complex stuff. You need to teach the basic concepts, step by step, before moving on to more complex stuff. But the authors are so keen to move to the "fun" stuff they skip over the required base knowledge.

Real world examples tend to have a huge amount of unpleasant details which hinder transfer of the underlying concepts. We teach one step at a time, and even then 99.999% of the people leave before finishing. Suppose you start teaching arithmetics by introducing 5 year olds to elliptic curves…

-- from a comment on HN

I see this problem when I'm trying to learn new technologies not directly related to the day job, where I see the problems beginners struggle with. Some examples:

• Want to learn frontend? You have courses that teach you what an 'a' tag is in HTML and how to colour your text with css; and then jump straight to "And now we will build this complex Bootstrap theme". And I'm like, wait, there are more steps here.
• Here's how docker works– run a Hello World example. Got that? Good, now we will show you how to use k8s to deploy a HA cluster.

The "I'm writing to impress Reddit/Hacker News" Problem

This can also be called the "Shove too much shit into one article, so I can please the Google SEO spam masters, and also impress the chicks/dudes on Reddit."

A real-life example: I was reading a tutorial about Django, and the author started by asking us to install Docker "To isolate our code".

And I was like– Django (unlike data science libraries like numpy / opencv) is written in pure Python, and so has no problems in a simple virtual env. But the author wanted us to use Docker– which outside of Linux world, has always caused me problems.

And after a few chapters, I realised why. He wanted us to use Postgres database. Again, I was like, why? Why not use Sqlite, which is easy to install and remove, and doesnt need docker?

"Because Postgres is an industrial standard database, and you need to learn how to use it".

That's fine– I have full courses that teach me just how to use Postgres. Why don't you focus on just Django?

Ultimately, I just abandoned that blog. Even though I had used both Django and Postgres in the past, I found it hard going. I just wonder how people new to programming feel.

I've seen a similar problem in paid books. From a recent book I bought on Go servers: "Know the basics of the Go server? Then you are ready to use MySql". And I was screaming "No I'm not, you haven't even covered testing yet!" I could have spent some time getting Sqlite working with Go, but groan its more headache I don't want (especially since I bought the book to avoid having to Google this stuff).

Another book abandoned.

Relevant comment:

When you're teaching something new, you want to be able to isolate that concept/technique and focus in on it. A simplified example, or a question with strict parameters, both allow the student(s) to concentrate on the key idea.

If you want to teach someone about SELECT in SQL, for example, it's useful to abstract away the database setup for that particular lesson. It's also useful to use a simplified database concerned with familiar entities, so that SELECT remains the focus rather than one new element of many.

Of course, these simplified examples shouldn't be used in isolation. Instead, you should have a number of them, eaching illustrating/assessing some small point or idea. Once the students have absorbed those ideas, then you start combining the initial building blocks into more complex ideas, just as you'd take a tiered approach when testing software; start with unit tests, then build up.

Why do people shove so much stuff into one post? One is to please Google, which loves all the keywords. Look at all these spammy sites on the top of Google.

Search for "How to run a command inside docker", the 1st few paragraphs will be: What is docker, why would you use docker, who created docker etc etc

All useless crap that doesn't answer the question but helps rank the site.

A second reason I see is: Authors get attacked on Reddit/HN for not being perfect enough for someone's taste. Actual comment on Reddit to one of my posts:

For a site that claims to be called Python for Engineers, the author seems to know little about software engineering. He doesn't use virtual envs and the code isn't pep8 compliant

The blog post in question was a 500-word blog with like 10 lines of code, and yet multiple commenters criticised me fOr nOt beINg a rEAl engIneeR

I know this gets to some people, and so they start writing defensively, anticipating any criticism and overcompensating for it. But here's the deal: People will always find something to attack you for.

I just stopped reading comments to my own blogs on HN/Reddit. Even if I get a thousand upvotes (which means the community as a whole likes it), the top comments will usually be mean spirited nitpicking attacks. No thanks, I'll pass. Like Steven Yegge said at one point, if you hate what I'm saying, feel free to write your own blog explaining why. But that is hard work, and so no one will do it.

Feedback for Creators

If you are a blogger or course/book creator:

• Focus on teaching one concept at a time
• Don't worry about "best" or "industry" practices– just teach the basics first
• Repeat a lot– beginners need to read a new topic multiple times before they will understand it. Don't assume because you covered it once that they "get" it
• Write to help beginners, not impress randos on social media

I should end with an example of a great book– Django for Beginners by William Vincent. It doesn't assume anything; in every chapter, the author revisits every step.

So in every chapter, he creates a new virtual env, a new project, sets up the urls/routing etc. So the 1st 20% of each chapter repeats the same basic steps.

At first, I found this a bit slow, but later I realised the constant repetition made sure we understand every single thing being taught. It (and the follow-ups) really are great books that finally made it click for me about how Django works.

Another good example: for DevOps, the Kode Cloud paid courses (which I got on Udemy). They all teach one small thing at a time with lots of examples and practices. No wonder the courses are top-ranked on Udemy, though they are comparatively recent compared to other courses.

tldr; Go slow. Repeat a lot. Don't skip steps.

(I want to add: And you will make a million dollars, but I'm worried I'll end up on the owl reddit, so I won't :) )