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.

What Is WebPack In VueJS & What Is It Used For? A Simple, Jargon-Free Guide

Do you remember in jQuery how when you wanted to add additional functionality than was provided, you would have to load in library after library in order to get what you wanted?

After a while, it probably became very cumbersome to manage didn’t it?

It probably ended up looking something like this: 

[image of too many script source tags loaded in]

You would have to add in a bunch of different script tags, load them into the relevant documents, and then on top of that, make sure that they weren’t conflicting with each other. Which they unfortunately, usually were. And then when they were, you were given highly obscure error messages at best in order to deal with them.

In VueJS, while you are able to do things in the jQuery multiple script src tag way, there is an alternative that is also available.

That alternative works from the command line.

That alternative is Webpack.

What Is Webpack In VueJS?

While Webpack is infact available to any JavaScript based project, we are only, for the purposes of this tutorial, going to focus on it as it pertains to VueJS.

Before we get into what Webpack is, we first must understand why it exists in the first place. We will know that by understanding the problem that Webpack solves.

The Multiple Scripts Problem & How Webpack solves this

What Webpack fundamentallly does is make your VueJS (along with a variety of other frameworks) development process easier. 

Before we get into how it does this. Let’s first take a step back and understand why Webpack exists in the first place. 

As the web evolved, two fundamental problems began to emerge for developers. 

  1. Too many libraries. To meet the UI demands of the modern web (link to post that explains why here), more and more external libraries and plugins were needed within projects. This got to a point where you could be needing more than 100 external libraries for your project at any given time. Sometimes many more. Imagine 100+ script src additions within your html file. This would be unmanageable.
  2. Speed increasingly becoming important. To respond to the increasing demand for performant, responsive, desktop-app like UI’s that was now necessary for the modern web, many developers DID opt to go for simply adding in a bunch of libraries directly. This, as you can imagine, lead to increasingly slower and slower UI’s and load times. This also lead to a dramatic decrease in the user experience. I think you can probably remember this time period. It was around 2011/2012 when jQuery was just reaching its peak. In response, many services such as Google, responded by imposing penalties for sites that were deemed to be too slow for the user, so that the fastest sites ultimately rose to the top. The consensus gradually became that the web and its websites just had to get faster, no matter how many libraries needed to be loaded. The web needed to become more efficient. Knowing how the economics of the web work, especially when Google institutes a penalty, the result of this became that web developers now made speed a priority. 

To respond to all of these increasing concerns a solution, ideally, a simple one, was needed.

In came Webpack.

How Webpack solves the multiple scripts problem

Instead of having to load in multiple libraries and manage them in an obscure way, with Webpack, you could now simply load in and manage your libraries within your command line. Using what is known as a ‘build’ script. These libraries would be loaded and stored within discreet folders in your project library and then made easy for use and loading when necessary.

Webpack would also make it easy for you to compile your newly loaded web libraries, so as to make the speed at which these libraries load much better. As well as this, Webpack would allow you to use new JavaScript functionality (such as ‘require() for modules’) within your code that was not readily available in modern browsers.

It could do this because you could write the code you wanted in your pre-compiled, or ‘built’ scripts, and then once you were ready, you could ‘build’ and compile them down into a format that the modern browsers could read and understand. Thereby unlocking a massive amount of new functionality.

While Webpack fundamentally is a JavaScript library bundler, it also allows for more useful functionality to occur during that bundling process.

Functionality such as:

  • Linting. Which is the analysis of your code for any potential errors.
  • Custom Loaders. Because Webpack by itself only understands and compiles JavaScript, custom loaders can be introduced to it in order to allow for the understanding and compilation of more types of resources such as CSS and images.
  • Plugins. Which allow for custom tasks to be run on your scripts at compilation time, such as the injection of custom data (ie. environment variables) and/or the custom optimization of your compiling bundle.

All of the above can be summarized as part of the hook functionality that Webpack provides. This basically creates a way to ‘hook’ into the bundling/build process as it is going on and manipulate your scripts in various different ways, with various processes, such as the ones listed above.

How To Use Webpack (Within A VueJS Project)

How Webpack works within a VueJS project

Just like the starting point of any Vue app is in the initial Vue instance. Likewise, the starting point of any Webpack build is in what is known as the ‘entry file’. This is simply the file that is specified within the webpack.js.config file as the place that Webpack should read to find and then bundle our imported modules.

In the case of a Vue project, this entry file is usually the ‘{}.js’ file. We will jump into this in the demo project in a minute, but before we do that, let’s get a reminder of what loading in libraries (modules) is like without Webpack.

Vue without Webpack

Vue without Webpack or any other bundler, looks a lot like jQuery in terms of folder and file organization.

You simply have a lot of libraries being loaded into the pages that need them, one by one. Usually within your header section in your HTML page. Like this:

<!DOCTYPE html>
<html>
    <body>
        <h1>Your Non-Webpack VueJS Project</h1>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/vue/2.6.11/vue.min.js">
        </script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/axios/0.19.2/axios.min.js">
        </script>
    </body>
</html>

Here you can see that we are directly loading in our standard VueJS script and then below that we are loading in our Axios library. Which is a popular library that simply allows us to run HTTP requests.

Note: In Vue as well as in other well known JS frameworks, what we normally used to call libraries are now commonly referred to as ‘modules’. This is largely due to the influence of Node.JS and the way in which these libraries are presented within the code.

They are typically loaded in, as we will see below, in the way that ‘modules’ in other languages and frameworks, such as Python do.

We may use our loaded in Axios library above, like this:

<div id="app">
  {{ info }}
</div>

new Vue({
  el: '#app',
  data () {
    return {
      info: null
    }
  },
  mounted () {
    axios
      .get('https://api.coindesk.com/v1/bpi/currentprice.json')
      .then(response => (this.info = response))
  }
})

You will note here that the above seems pretty straightforward. But remember that we are only loading in one library. In most projects that are required to meet today’s modern level of complexity, as much as 20-100 different libraries could be needed. Sometimes much more.

Since we need them all. The best thing to do to make them manageable is to simply bundle them up and automate this process so that we are not having to deal with each one, one by one. This is what we do with Webpack.

Vue with Webpack

Using Webpack changes the way that you both write your code, as well as the way in which you organize your folder structure.

While in our previous ‘without Webpack’ example, we could get away with putting everything in one page, and simply loading in our libraries from a CDN. Doing this massively limits the potential of our application and what we can ultimately do as developers.

This style of organization, both in terms of code and overall project structure is simply too primitive to deal with the demands that modern website building entails.

The Modern web project code and folder structure, and how it all works (In Vuejs)

The folder structure

The easiest way to get started with Webpack within your Vue project is by using the ‘Vue CLI’. Check out the link to learn more about that if you don’t know already. We will skip the installation and jump right in.

This is the typical folder structure that we get from a full Vue project, installed using the Vue CLI.

[image here]

Within this structure, our Webpack basically coordinates everything that we’ve described above from within our webpack.config.js file. This is our command center. It is here that we set our ‘hooks’ such as our loaders (in this case we have our Vue loader set within it), as well as all of the other necessary plugins we need.

Loading in and managing libraries (modules) with Webpack within this structure is as easy as running ‘npm install {package you want}’ while within our newly installed Vue folder directory, in the command line.

In this case, we will load in Axios.

Navigate to your VueJS folder directory and type in ‘npm install vue-axios’.

This loads in and places our Axios library within the ‘node_modules’ folder within our directory.

The File Structure

Once we have done that, we will simply add in our imports of Axios in our Vue ‘entry file‘ {name of the file}, like this:

import Vue from 'vue'
import axios from 'axios'
import VueAxios from 'vue-axios'
 
Vue.use(VueAxios, axios)

What this basically does is place a reference for Webpack to know (as it has already been specified within our webpack.js.config) that we will be reading this file for modules that need to be loading in and bundled at compile time.

All of our loaded modules in the future will be referenced within this entry file.

There is no need to load in anything else after that. When we have written the code we need. We will simply compile with our Webpack enabled command, in this case, ‘npm run dev’ and it will handle everything else that is necessary to get it to work with our code.

Let’s now use our newly loaded library in an example to demonstrate what we mean here.

Let’s open up our App.vue file. We will be making a call to an API and then displaying our data to our root <div>.

[example code of the App.vue file]

Notice that the only things we have in this page is the code we need. All of the other parts of the code, such as the header, footer and other libraries are going to be bundled in once we run our Webpack script.

When we’re ready to view this code, we will simply run this script. Like so, within our command line, inside of the project folder: ‘npm run dev’.

This will bundle up our code, from its present and then push it to the dist folder as browser recognizable JS, CSS and images.

As you can see here. Webpack is not only allowing us to load in our libraries in a very easy way but it also, with the additional functionality it adds via its ‘hooks’, the loaders and plugins, allows us to unlock amazing functionality at a higher level in our projects, such as the ability to use custom ‘App.vue’ files and structure our projects in the way that this makes possible. Via the Webpack ‘Vue Loader’ in this case.

Webpack ultimately is a key component of the modern web. With the ever-increasing complexity that most developers have to now deal with and the endless array of tools that need to be managed, making the process of bringing them together and working seamlessly, as well as adding more useful, efficiency generating functionality on top of that, only make it greater.

With Webpack, your workflow, especially in VueJS, which is already making things easy, makes it just that little bit easier.

What The Vue Instance Is, And How It Unlocks The Magic Of VueJS

What Is The Vue Instance?

Before we can start to do anything with VueJS on our webpage, we first need to create a way for Vue to initialize and then ‘bind’ itself onto that page.

Just as in jQuery, nothing happens until we initialize our document ready function, like this:

$( document ).ready(function() { console.log( "ready!" );});

In Vue, nothing happens until we create our Vue Instance, like this:

<script>
new Vue({
    el: '#app'
    data: {
        
    }
})
</script>

Within the bounds of this Vue Instance, which is just a simple JavaScript object, we can write the code that Vue will recognize and then execute onto the page.

Let’s first take a deeper look into what is actually going on with this Vue instance object, and then we will talk more about what it can allow us to do on our HTML page specifically, and how it unlocks the magic of Vue.

Inside The Vue Instance Object

On the first line, we begin with the instantiation of our class object, which bears the title of Vue, like this:

new Vue({ }}

This creates and initializes the Vue instance within our browser.

Next, within our created Vue instance, on the first line of our object, we add in our ‘el’ option, which looks like this:

new Vue({
    el: '#app'
})

What this ‘el’ option does is simply ‘bind’ our Vue Instance to an element within our HTML (in this case, one with an ID of ‘#app’), allowing us to apply our Vue functionality to everything that is within that element.

Putting it all together, it would look like this:

<div id='app' </div>

new Vue({
    el: '#app'
})

As you can see, our <div> element, with an ID of ‘#app’ has been bound to our newly created Vue Instance. Another way that we can refer to this ‘binding’ of an element by Vue within the Vue instance is as a ‘mounting’ of, or to ‘mount’, an element. It means the same thing. Simply that we have attached our Vue instance to that element, in order to activate Vue’s functionality within that element.

A key difference to note here, coming from jQuery, is that rather than applying functionality to the entire webpage, as is done with jQuery, in Vue, functionality is only applied to a specific section of the page – one that is bound to a Vue instance (of which there can be many). In this case, our <div> element, with an ID of ‘#app’.

Lastly, we have our ‘data’ option. Which as you’ll see soon, is one of the most important parts of our Vue instance in terms of functionality. It looks like this:

new Vue({
    el: '#app'
    data: {
        someText: 'helloThereText'
    }
})

As you can see here, after creating our Vue instance and then mounting it onto our ‘#app’ element, we then set some data within our instance. This gives our mounted <div#app> element access to the data that is within our Vue instance object.

That data can now be used directly within our mounted HTML element, like this:

<div id='app'>{{ someText }}</div>

By placing the data variable from our instance within double curly braces, we allow Vue to recognize and then ‘interpolate’ the data as being from our Vue instance, in the example above. This data is then transformed into the text that it contains within the mounted HTML element.

On page load, the data held within our ‘someText’ variable above will be displayed out onto the loaded page as the text, ‘helloThereText’.

How The Vue Instance Unlocks The Magic Of VueJS

So from the example above, we can see that a Vue Instance is basically an object that is created in order to allow us to attach Vue functionality to our HTML.

Let’s now take a slightly closer look at what the Vue instance is and what it can do. The explanations below will aid you greatly in getting a deeper understanding of what Vue can do for you, and in general, what Vue is all about.

A Data-Driven Approach To UI Manipulation

Because Vue is primarily ‘data-driven’, which means that what happens on the page is simply a reflection of what happens in the data held by Vue, along with the changes to that data, the Vue instance can be thought of as a syncing agent that simply translates changes in the data held by Vue, to changes in our UI. And by doing so, keeps our data -> view connection ‘in sync’.

An example of this can be seen with the way that view allows us to handle conditional logic on our HTML page.

Below we are displaying or hiding an element within our Vue instance, depending on whether or not data (as a variable within our data object) is set to either true or false.

<div id='app'>
    <h1 v-if="is_it_true">{{ someText }}</h1>
</div>

<script>
    new Vue({
        el: '#app',
        data: {
            someText: 'helloThereText',
            is_it_true: true
        },
    });
</script>

In the current way that it is set up (with Vue’s v-if attribute, Vue attributes allow us to add Vue functionality directly to our HTML elements), our h1 shown above will show on page load. With the text ‘helloThereText’.

If we were to change the value held by our is_it_true variable within our data option to false, the h1 will disappear.

This is what we mean when we say that Vue is data-driven. It is driven, and changes on the webpage are made, by what happens in the data that is held by its instances.

The Vue instance, by giving us a simple ‘command center’ where we may set, and when necessary change our data, helps us to unlock the magic that is data-driven Vue.

What Is The DOM – (Book Excerpt – From jQuery To VueJS)

Imagine that you just hand-wrote a thousand-word Essay on the oh so glorious language of JavaScript. 

After you had finished that Essay, you decided that you wanted to change the first paragraph’s font color to red. To make it stand out more. 

Now, imagine that you had magical powers. And that you could simply do this by taking your hand, plucking the paragraph with your fingers, rubbing the paragraph in your palm to change the color, and then setting it back down onto the page. Wouldn’t that be awesome (and also a pretty cool party trick)?

This is essentially what the DOM allows you to do with web pages. In the case of the example above, the DOM would be the hand that allows you to pick up, manipulate and drop the elements and/or contents of those elements. 

The DOM is essentially an interactive layer that sits on top of a web page and makes it easier to interact with that page.

Within the DOM the elements and contents that we are referring to are called ‘nodes’. These nodes exist on a tree-like structure, that is best visualized as a flowchart. 

You can see an example of this here: [highlight what the different numbers mean – 9 signals document type, 1 signals an element, 3 signals content, and so on and so forth.]

What we have above is the general flow of a HTML document that is created and represented within the DOM. This is essentially how the DOM ‘sees’ a web page.

It is, essentially, an API for the Web Document, whether that document is in HTML, XML or another compatible format.

The DOM is like the fingers that allow you to pluck, structure and then interact with the elements from a page of an essay you just hand-wrote on a piece of paper, and manipulate them how you want, and then put them back onto the paper. Except in this case, that paper is the web.