Why Most Programming Tutorials Are So Hard To Understand – (And A Solution To This Problem)

To reason logically is so to link one’s propositions that each should contain the reason for the one succeeding it, and should itself be demonstrated by the one preceding it.

Jean Piaget

The above quote is from the Swiss psychologist Jean Piaget, a well-known figure in not just the psychological field, but also in the education field.

I want you, as you read through this post, to keep this quote in mind.

You will see why as you continue to read.

You might be asking yourself what the above quote might have to do with programming tutorials, and the answer is, well, a lot actually.

But before we can get to fleshing that out, we must first start with the core issue that I believe is the cause of hard to understand programming tutorials (and programming documentation for that matter).

That issue is one of ‘imposter syndrome’.

The Two Sides of the Imposter Syndrome Coin

I have a theory about imposter syndrome. That is that it is simply a symptom of a more profound problem.

That is the problem of believing that everyone is at the same level of knowledge that you are, and that they understand that knowledge in the same way that you do.

In the same way that the self-consciousness that seems to be produced by a lack of ego in, say, a social situation, is actually the result of a preoccupation of the self. Imposter syndrome is likely caused by too much of a focus on one’s own level of knowledge and a mistaken projection of that level out into the social world.

Jean Piaget also seemed to know this well:

Egocentrism is, in its essence, an inability to differentiate between the ego and the social environment.

Jean Piaget, The Moral Judgement of the Child

Egocentrism sounds like a bad thing, a character flaw almost. But it is in fact, simply a description of a very normal human trait. It is, at least according to psychologists like Piaget, how we began to think as children.

It is from this basis that, he believed, we began to gradually differentiate, or said another way, to ‘learn’ our environment, by a gradual process of both separating what was in front of us from ourselves, and then also, combining those things with other things and seeing how they would link and interact.

In this process, he believed, we would gradually ‘build’ knowledge structures from the ground up. These structures would be the representations of the things we were seeing as well as the links between those things, a schema of sorts, of all the things that we had, over time ‘learned’ and connected within the web of our knowledge structure. This with all preceding knowledge serving as the foundation for all the knowledge that would succeed it.

Sound familiar?

This method of learning proposed by Piaget is what became known as the constructivist theory of knowledge.

Jean Piaget’s development of the constructivist theory of knowledge was probably a direct response/result of his discovery that we (including people who teach) have a natural inclination to believe that our own level of knowledge is also the level of other people. A form of ego-centrism that is inherent within all of us. The constructivist theory of knowledge says, in contrast to this, that we should be more empathetic. It encourages us to first endeavor to exercise empathy with our potential student, to try to know what the learner already knows, and then, and only then, from that foundation, begin to teach and further ‘build’ their knowledge base.

This is what most programmers who make tutorials fail to do. And it is not really their fault. With the mass proliferation of tutorials that we currently have, it is easy to forget that teaching is itself a skill. One that needs to be trained.

Without the fundamental empathy needed to meet the learner at his or her level, the teacher, in this case, the tutorial maker, will simply be making too many assumptions, based on his own level of knowledge and therefore be building a structure on a foundation that may not even be there.

This is very often the case with programming documentation in particular.

Ever had to Google most of the missing pieces in an installation process, simply because the author had assumed that you already knew certain parts of it? I know I have, on numerous occasions.

So how does one solve this? How do you go about 1. Gaining the empathy with the learner necessary to create a great tutorial. And then 2. Effectively teach and ‘build’ on the learners existing knowledge structure?

Let’s start with 1.

How To Gain Empathy With Your Learner As A Tutorial Maker

The sheer amount of ‘foundation’ or level of knowledge that is needed nowadays, means that the depth of the research process that you undertake as a teacher must strive to match it.

Fortunately, we live in an era where the level of depth in one’s research that can be achieved is relatively high.

By depth, I am referring to the amount you can know about your learner’s current level of knowledge.

The way in which you will do this will be two-fold.

  1. Target a specific type of learner. Know who exactly it is that you are trying to teach.
  2. Gain empathy for the learner’s level of Knowledge. By building a mental model of the current foundation that the learner has.

To achieve one, you must simply try to visualize in your mind’s eye, a specific person that you would like to share knowledge with. In this, you must be very specific.

The best person to target in most cases is yourself, as you have an infinite amount of knowledge about this demographic.

Doing this well will reveal many of the traits as well as the likely habits of the target learner. This arms you appropriately to be able to do the next step.

Once you have gotten yourself a clear enough picture of who you would like to teach, the next step is to gain empathy with the target learner and then gradually build a mental model of their current level of knowledge. This is done by seeking out the places where your target learner hangs out. This can be on sites such as Reddit, but even YouTube videos and comments, as well as things like Amazon reviews, can serve as good sources. Anywhere your target learner is likely to be and has an impetus to be active in some way (such as by making a comment) can work well.

Once you’ve done this, simply observing them and over time, gradually building up your mental model, you will begin to slowly develop a clearer picture of your learner’s current knowledge structure. This can take as little as a day to a week, depending on your level of skill in this, as well as how much your mental model already matches that of the target learners.

Once you have gotten yourself this synchronicity with your learner. You are now able to move on to the next step.

You are now ready to teach.

How To Teach Effectively, The Constructivist Way

We learn best when our neurons get ‘switched on’, or activated.

This activation of neurons then helps to facilitate the ‘linking’ or ‘absorption’ of new information that occurs when we learn. 

Neurons are best activated by novelty. Learning or experiencing something new. Like a new language or framework, for example. 

What this activation does is simply prime the brain for information storage. 

It gets it ready to build on the knowledge structure.

Once this happens, the brain then begins to store the new information by following a process of searching for pre-existing information within the brain and then linking or ‘associating/absorbing’ the new information with the MOST similar information to it it can find. Ultimately building a new knowledge structure or concept. 

The key words in the last paragraph are ‘searching’ and ‘most’

You see, the more similar the associative link is that the brain uses, the faster, and more efficiently the brain can absorb that new information. Because the brain can now leverage the other related relationships that that link has, which are likely to be similar to the relationships inherent in the representation of the new information.

For example: Let’s say that you just saw a spoon for the first time.

Your brain wouldn’t store that new information as simply a spoon just like that. It would have no basis upon which to do so. 

It would instead first look for what it already had stored in there that was similar to a spoon, say, a fork, and would then store the spoon as a fork-like-thing, in relation to the fork. The representation of a spoon in the brain would then actually be attached to the representation of a fork. They would be linked – neuron to neuron. And in that process, the learning of a spoon as a concept represented in the mind would occur.

The brain then, would interpret a spoon to be something like a fork but with a rounded top and no gaps. The concept of a spoon could only be ‘learned’ or said another way, ‘absorbed’, and then subsequently exist in the brain, as an extension of the concept of a fork.

So using this example of the fork and the spoon. The only truly new information that needs to be stored is that of the top side of the spoon and its difference with the fork. The brain leverages the knowledge of the bottom side (the side you hold with your hand), and saves the energy of having to store that again. If you now, on top of priming the brain with novel information, like a new programming language or framework, present that new information with the best associations that the brain can leverage, such as the most similar languages and frameworks to the novel one, you effectively eliminate the searching process that the brain has to typically go through on its own. With the end result that you massively increase the speed of absorption and learning.

This is what we mean in practice when we talk about teaching with a constructivist approach.

The emphasis is on first, gaining empathy enough that you can see the pre-existing knowledge structure in your learner that can be leveraged. And then once you’ve grasped that, pulling on that structure in order to efficiently store new information into it.

This approach, if applied well, can make your programming tutorials and documentation easier to understand for your learners, and simply that much better overall.


This is the style of teaching that we use within our books and courses at FromToSchool.

We are creating the first programming books that aim to focus strictly on teaching new technologies to experienced developers, using the languages and the frameworks that they already know. No brain searching needed. 

Our goal is to not only allow developers to increase their learning speed in order to keep up with and match the speed at which technological change is taking place, but to surpass it. Be sure to check out our books and courses if this approach and article interested you and you’d like to learn more.

You may also subscribe to our email list below to be the first to know when we publish a new post or book.