By May 1, 2020

The 5 Principles Of A Great Programming Tutorial

programming tutorialOver the last few years, many programmers have—almost unknowingly—become educators.

With the increasing rise of people wanting to learn to code, there has been a corresponding rise in the number of people willing to teach it.

There are a lot of paradoxes in the field of programming. For example, the more of other people’s code you use (i.e., via JavaScript’s npm packages or via PHP’s Composer packages), the simpler the implementation of your own code becomes—while at the same time, the more complex your overall code base becomes.

Very often, we find that one thing that seems to be the complete opposite of another thing is in fact the cause of that other thing.

Another example of this paradox is that of imposter syndrome, which can be defined as a lack of internal acknowledgment of your own level of knowledge and accomplishment. It is a commonly discussed topic within the programming world, but one whose cause and subsequent effect are rarely mentioned.

The thing is, you are probably a lot better programmer than you think. Therefore, you should be conscious of the effect of imposter syndrome and the paradoxical manner in which it changes the way you teach.

We’ll first see how exactly imposter syndrome affects your teaching. We’ll then take a look at the role of empathy in the process, and how it’s crucial for overcoming imposter syndrome and creating better tutorials. Afterward, I’ll share with you the five principles of creating a great programming tutorial.

Why Imposter Syndrome Leads to Poor Teaching

More and more people have gradually come to admit their own feelings of imposter syndrome. The cause of it has also simultaneously begun to emerge.

It seems that the main reason why imposter syndrome occurs is that, although most people who are experiencing it are in fact very competent, they unfortunately overestimate other people’s level of knowledge in proportion to their own.

Essentially, what this means is that most programmers who feel like imposters feel that way because they presume that their own level of knowledge is also the level of those around them.

Usually, these programmers are wrong.

The ironic thing about imposter syndrome when sharing knowledge is that often, because of the paradoxical effect that it has, the person who feels like an imposter will end up “over delivering” to their learner. Because they feel like they don’t know enough, they try to prove how much they do know.

The paradox is that they ultimately end up missing the mark. Another way of looking at it is that programmers with imposter syndrome assume that their learners already know what they know. And that assumption leads the teacher to share at a higher level of abstraction, which means they might miss what the learners don’t know.

These gaps in knowledge then don’t allow your learner to build their “knowledge structure” in the same way that you’ve managed to.

This mismatch of perspectives gets you out of alignment with your potential learner.

Those gaps need to be filled first.

But how do you do that?

Empathy and How To Efficiently Build Knowledge

The key ingredient in any exchange of information is relevance.

What’s relevant depends on the receiving party’s needs as well as the giving party’s ability to provide for that need.

This alignment or understanding of needs can be summarized by saying that the two parties empathize with one another.

Empathy is what allows information transfer to have its relevance, therefore allowing it to be transmitted in the most efficient manner possible. Empathy is a key component in teaching; when you build empathy with your student, you can create effective tutorials.

It is also via empathy that you can gradually begin to build an understanding of the knowledge structure within someone else’s mind.

The key component in effective teaching.

Which is simply, as we’ve stated above, an exchange of information.

Let’s examine it below, by outlining what I believe are the five key principles of all great programming tutorials.

5 Principles to Follow for Great Programming Tutorials

Perhaps you’ve never considered how empathy can help you make better programming tutorials. If so, maybe you’re not sure how to proceed. But don’t worry! These five principles will definitely help you get off to a good start.

Have Deep Empathy With Your Reader, and Avoid Making Knowledge Assumptions

When we talk about empathy in the coGreat Programming Tutorialsntext of teaching programming tutorials, what we mean is that you have a relatively accurate picture of what your learner already knows.

You may build this empathy by conducting research on your learner. This can be done by first gaining a reasonable understanding of who your target learner is, by specifying the level of knowledge of your target learner, where they typically hang out and share online, and what they typically talk about.

If, for example, you were teaching a React tutorial, you might go onto a community site like Reddit and seek out the /r/ReactJS subreddit.

Let’s say you are targeting beginner React developers with about one to two months of experience. You could do a search for “one to two months” or “beginner” on the site and start to read through the posts.

You will start to get an idea, as you read through, of just what that particular learner knows and does not know.

An example of this is TheNetNinja—a free YouTube-based tutorial series that walks you through new technologies step-by-step.

What’s great about this series is the laid-back, almost common-sense, “ya got this, man” style of presentation that TheNetNinja has. This is likely due to the high degree of empathy that he has with his learners.

Understand the Topic Deep Enough That You Can Use Metaphors to Describe It

The brain learns primarily by metaphor. In order for you to be able to teach using this very effective method, you must first understand the metaphors that will actually “work” with your target learner.

Assuming you’ve followed the first step of gaining empathy with your target learner, doing this should be relatively easy.

An example of this is Paul Graham; his tagline is “Make something people want.” He’s all about building and using empathy, by the appropriate use of metaphor within his educational content, including in his tutorials and articles.

Have a Conversational Tone

See your reader as a friend who you are simply having a conversation with while explaining a topic. The best way I’ve found to make sure that the writing is flowing like a conversation is to read it out loud to yourself and see how it feels.

If it has an easy-going yet informative conversational tone, then you’re on the right track.

An example of someone who does this well is TheNewBoston. He has pretty much cornered the personality-based online tutorial market, to the extent that many of his sayings are now often copied by other online tutorial makers. “What is up guys, this is Bucky” is probably his most well-known catchphrase.

Guide the Reader

Ultimately, your goal is to help the reader learn something. The most conducive way for that to happen is for the reader to feel like you are taking them on a journey, and that you are simply their knowledgeable guide.

The example above, TheNetNinja, does this exceptionally well in his tutorials.

His format is simple. When introducing a new topic, he typically begins by first showing how not to do something, or the alternative, harder way of doing something, which teaches some portion of what he wants to teach. He then follows this on, with the simpler approach, which not only teaches you something new, but also reinforces the previous, foundational point he outlined with his first example.

Use the Constructivist Approach When Teaching

With a constructivist approach, the emphasis is on first gaining empathy with your learner, and then, once a mental model of that learner’s level of understanding has been formed, going on to use that knowledge structure that the learner has as a foundation to build on top of.

An example of this is FromToSchool. The entire philosophy of FromToSchool is built on the premise outlined in this post. FromToSchool creates content that allows developers to learn new programming languages and frameworks, faster, by using the knowledge of languages and frameworks that they already know.

If you’re worried that you don’t know enough to be a teacher, you might overcompensate with too much knowledge.

If you overcompensate, you might end up going over your students’ level of knowledge, and ultimately, over their heads.

Tutorials Are About Empathy

Tutorials Are About EmpathyFollowing the above principles will give you a very solid foundation for your tutorials. In applying these principles, you will give your reader a rock-solid framework within which to navigate the new knowledge that you are trying to help them learn.

In the end, creating great programming tutorials is about empathy: understanding your readers’ needs and what they expect from you.

At the same time, and in order for this to happen smoothly, you must also understand your own needs. In other words, you must be able to give yourself credit and realize your strengths. This will help you find the balance with your readers.

Good luck making your tutorials!

About the author

Tapha Ngum

Tapha is the Founder of, a simple tool that brings your entire web and mobile UI/UX design planning process into one simple place. He also maintains a blog at FromToSchool, which helps experienced developers learn new languages and frameworks faster by leveraging the languages and frameworks they already know.