CodeAnalogies Blog

In the fall of 2014, I started the long, painful journey towards learning web development.

Since I had a day job, I knew that this process was going to consume my nights and weekends. And, since I had never taught myself any technical skills online before, I was aware that there were plenty of unimaginable challenges that would rear their ugly heads along the way.

But here is what I could not anticipate: After using hundreds of written, video and interactive tutorials, I found that the methods for teaching technical topics online were incredibly… primitive.

The State of Online Coding Tutorials

There are thousands of tutorials written per year on HTML, CSS and JavaScript by developers with tens of thousands of years of collective experience. You would think that there would be a rich ecosystem with a variety of teaching methods and interactive tools.

Not the case. Instead, coding tutorials simply repackage 20th century teaching techniques with 21st century technology.

Video tutorials mimic a classroom lesson with a whiteboard. Or an instructional DVD you could buy from an infomercial.

Written tutorials act like chapters of books.

Interactive tutorials act like compilers that have been used in colleges since the 80s.

After spending night after night learning new topics and trying them out in test projects, I thought that I HAD to be doing something wrong. So I began asking friends what they thought I should do differently.

College-educated computer science majors asked me: “Have you tried reading the docs at W3 Schools or Mozilla Developer Network?”

Other entrepreneurial people told me: “Give up now. I couldn’t learn it when I tried.”

Self-taught web developers asked me: “Why are you talking to me? You have hundreds of hours left if you want to learn web development.”

Reading documentation. Give up. Put in more hours. Those were my options.

I kept on putting in the hours until I could build a full-stack web application. It took a full year (at least). These hours were spent re-watching, re-reading and re-doing tutorials until I felt like I “got it”, then trying the concept in a project.

I felt like I had not really progressed from painful study habits I had to use in college. It was shocking that thousands of other newbie web developers would need to complete this journey.

So, I set out to find why these technical tutorials led to hours of confusion. I read books and papers in the field of cognitive psychology, looked at popular explanation tactics and also wrote my own series of coding tutorials.

Here are the 5 reasons that an Internet full of coding tutorials still could not provide satisfying lessons (and how to do better).

Mistake #1: Teaching By Showing Code Snippets

Let’s compare coding to cooking. Both require you to dutifully follow a set of instructions if you want a reasonable output. Both have hard rules with no room for error.

For some reason, tutorial creators love to put a snippet of code on the screen quickly after describing a concept for the first time. They will provide a line-by-line explanation of the code, as if that is enough.

There are no clear associations between different lines in the code snippet above, unless you are an intermediate Node.js developer and you know how to write an HTTP server.

If I was trying to teach you how to make a sauce, this is equivalent to showing you a picture of each component of the sauce in its prepared form without showing you how to get there. You could figure it out, but it will take plenty of trial and error.

Is this diced tofu? Diced onions? Diced fennel? How big are the chunks? What tool should I use to dice them?

Of course, if you want to become a proficient cook, you don’t want to learn how to dice onions over and over again. I want to teach you once or twice, and allow you to recall independently every little step from full onions to diced.

If there is multi-step process to learning how to create an HTTP server (like the example above), the code snippet should be the last part. It should not be the first (or whole) process. And the whole context must be taught together.

This is because your brain stores long-term memories in the hippocampus via associations. The hippocampus needs context in order to store a new concept with related concepts. Context, in this case, is not the adjacent lines of code with individual explanations.

Instead, new web developers would have a much better chance at storing the concept of an HTTP server by associating it with something they already understand. Your brain needs to create a rich network of connections to successfully store new challenging concepts.

Here are some ways that your brain could better understand the components of an HTTP server:

1. A analogy that explains the different parts of the code block and uses existing relationships to explain these new relationships.
2. An interactive version of the code snippet that shows the live state of the application. When you change a line, you get an instant response on what happened to your request.

Mistake #2: Failure To Consider the 80/20 Rule

If you interview a web development teacher or 10 new web developers, you will hear about the same challenges over and over again. CSS positioning. Floats. Callbacks. These have been the most common challenges for the last 10 years.

For some reason, though, tutorials will still teach each concept for the same amount of time. If a lesson on introductory CSS is composed of 10 lessons and is expected to take 5 total hours, each lesson will be approximately 30 minutes long. The easy ones are taught for exactly as long as the tough ones, even though there is a well-documented consensus on the toughest topics!

It’s like teaching how to break an egg versus how to carefully sear a gourmet chicken breast. Both are equally important to make a great meal, but one requires much more practice. But, you may be misled to believe that they are equally difficult because cooking a chicken breast perfectly appears from the outside to be a straightforward job.

New developers solve this issue in a couple ways:

1. Assume they are the dumb ones and give up
2. Consult other tutorials on the same topic, which will be largely repetitive and occasionally poor quality. The “spray and pray” approach.
3. Proceed to the next topic with the assumption they will “figure it out later”

Teachers from other disciplines will use an 80/20 analysis to refocus their efforts. This means that 20% of new concepts will consume 80% of student learning time.

The 6 CSS topics might be equally necessary to build a beautiful website. But they are NOT equally easy to learn. Some create hours of struggle.

In an ideal world, a full CSS curriculum would include 2–3x more material on these common challenging topics. It would include positive encouragement (“Everybody struggles with this!”) and extra practice opportunities. But, this has not happened yet, and I do not expect that it will ever happen for most popular services.

You know you are stuck in this rut when you have been trying to learn a new concept for hours, and you still cannot predict what will happen if you tweak one line of code. You can use the Feynman Technique to determine the topics that you do not fully understand:

1. Choose a Concept
2. Teach it to a Toddler
3. Identify Gaps and Go Back to The Source Material
4. Review and Simplify (optional)

Mistake #3: Teaching From Perspective of an Experienced Engineer

Many introductory coding tutorials are written by engineers with 10+ years of experience. How do I know? Because I had to re-watch or re-read tutorials over and over again until I realized, “They are not going to explain this key concept! I am going to need to search the Internet for an explanation before I can continue.”

This is actually a well-documented cognitive bias called the “curse of knowledge”, and it happens across all technical disciplines.

Here’s what it means- when teachers have years of experience with a technical subject, they have already created a deep understanding of the subject. Since they are blinded by the connections in their own brain, they cannot understand how a beginner might view the new material.

If you recall the way that your brain stores memories from above, this actually has a biological basis! The teacher’s hippocampus has formed associations that are not present in the brains of students.

To overcome this challenge, I recommend a tool like FreeCodeCamp that was written by self-taught web developers for others in a similar position! It has a full curriculum that is specifically meant to help self-directed learners overcome hurdles.

Mistake #4: Teaching Code Like It Is a Mysterious New System

Let’s go back to the cooking comparison. Most people have been cooking SOMETHING their whole lives, or were taught the basics by parents. They are already familiar with all the basic tools from years of trial and error. So, if you were teaching a person to be a professional cook, you would already have the basics to build on.

But there is no “basic” version of learning web development! Even if you have learned R or Java in the past, there still won’t be many lessons that carry over.

So, how do most online tutorials take this into account? They include lessons that teach code like it is a fantastic new world, full of HTTP servers, finicky browsers and asynchronous events. They act like these complicated pieces are the foundation for later advanced learning.

Imagine if cooking required such a high barrier to entry. We would all be eating microwave food. Cooking engages all 5 senses and makes the right procedure and the wrong procedure quickly stick in your brain. The human brain learns best when engaging multiple senses. It can understand systems when different stimuli make good vs. bad obvious.

Now, I know this seems impossible. Since all the code runs in a browser or on a server, how can it connect to our senses? And I don’t mean watching a

Instead, Kalid Azad from BetterExplained uses a graph with an x and y axis to help you visualize the “imaginary” dimension. Now, the concept of imaginary numbers is tied directly to a familiar concept. No memorization needed.

Mistake #5: Lack of Immediate Feedback

On the surface, it might seem like web development already has a perfect system for feedback. After all, as soon as you refresh your browser or type “npm start” into the console, you get an immediate response.

In the cooking analogy, let’s say you are trying to perfectly cook a chicken breast for your meal. Instead, you burn it. What could have gone wrong?

1. Sliced it too thin in the first place
2. Turned the heat up too high
3. Put it in the pan too late
4. Left it in the pan too long

Your burnt product at the end gives you no clue as to what went wrong. Only years of experience or countless attempts using trial and error will help you figure out what went wrong.

Here is the error message you would get if this happened in a command prompt:

That is not going to help with debugging! It encourages learning by trial and error until, hours later, you figure it out. Instead, you need a feedback system that alerts you to the impact of each decision:

The visual above shows that on step 2, “Highest Temp”, something went wrong that ruined the output.

This rich network of possible decisions is already embedded in the brain of expert chefs. And even intermediate web developers can read an error message and focus their debugging efforts on one part of the script. But beginners have no similar instinct, and today, they only learn from hours of trial and error with intermittent feedback.

Again, this may seem impossible to pull off in a text editor or online editor like CodePen. But, Bret Victor’s famous essay Learnable Programming has already outlined an entire framework for helping new programmers get feedback on every line of code in their script as soon as they are typed.

Self-Taught Learners Are Hurt The Most

If you are in high school or college, you can deal with a sub-par level of teaching. You just need to prepare for the next test, and you have a support network of fellow students. You are evaluated on whether you can get a score on a test, not whether you can get paid to practice the skill in real-life.

But if you are a self-taught web developer, you probably face different circumstances. You have a limited amount of time, and you are going to need to prove your entire skillset by building a real app or passing a test during a job interview. There is no concept of studying for a test and then moving on.

As the online education industry grows and more adults are forced to learn new skills online, I predict that the power will shift towards the learners. There will be increasing pressure on online education companies to improve the learning experience itself. The best teaching strategies will be rewarded with hundreds of thousands of paying subscribers.

—

Want to learn web development with simple explanations? Sign up here.