At CódigoFacilito we've been teaching programming for over 8 years now, with hundreds of thousands of active students.

Let's say you decided to learn something new today, you want to update your knowledge to some new shiny technology, let's say you as a JavaScript beginner decided that you want to learn GraphQL.

So you search for an awesome course, or a tutorial, a post, whatever you prefer and the person behind the tutorial starts with a basic server, a database and you hear something like "Well, now let me add some quick validations" and then he proceeds to write like 15 lines of complex validation codes, because well... best practices.

 Best practices vs Learning

To follow up with the previous example, a person, a new student decides that He or She wants to learn GraphQL, only to face himself or herself with the need to learn validations, or anything not related to the main topic (GraphQL in this example), only because the teacher decided that it's imperative to follow best practices, because what good will we do if we teach something without those precious best practices?

This is for me one of the easiest way to scare someone who is trying to learn something new, flow his or her mind with concepts unrelated to the main topic, throw lots of complex code to decorate your example, use complex analogies that only overcomplicate a tutorial just because you want to teach a real world example.

The other side of the story is using examples that are too far away from the real use cases, to teach something in an scenario so controlled that going one step away from this scenario means that the student no longer knows what to do, because he didn't learn the technology properly, or pushing him to do bad code because that's the way he learnt the technology.

This is the eternal battle educators face every time they produce content, is this part of code necessary to understand the main topic? is this example too complex? is it too easy? can he use this to build new and different examples?

So what can we do?

Set yourself in the middle

After teaching dozens of courses in programming topics at CódigoFacilito here are some recommendations I could give you to produce better examples for your programming tutorials:

1.- Prepare your entities

In most programming examples we have to deal with entities, like it's pretty common to use animals as entities while teaching OOP.

I'd recommend to use real world examples, but don't take them too far away, for example, there are very low probabilities to code something using an Animal class and a Dog one that inherits from it, so stay away from those kind of examples.

Some very good example I've seen around are Blogs(Article,User) for MVC, To do lists although very common are a good example, Documents (like with words and titles, and so on), Courses, Videos, Playlists, etc.

Don't use something that is too conceptual, like Animals, use something that can be code and I'd be useful, that does not need more than 3 different entities to work.

2. Don't do it unless is crucial

Let's get back to my validations example in a GraphQL tutorial, although validations are important, they are not a crucial part of teaching GraphQL, in fact, you could be a series of its own about validations, so, I'd not use validations in a GraphQL tutorial 😱.

There are two main reasons to ditch what's not crucial while teaching something.

1. If you're an expert, you already know how crucial validations are, and probably, you already know how to write validations so it's likely for you to get bored while listening to something that does not belong to the topic you searched for.
2. If you're a beginner, well, probably you're gonna get lost in this part of the tutorial, and and most importantly, you'd get wondering what does validations have to do with GraphQL? are validations GraphQL? does every GraphQL developer work with validations? how can I separate these concepts?

By throwing advanced knowledge from the sake of best practices you're demanding the user to get bored, or frustrated, you're probable making herself or himself feel dumb, or you're confusing him or her.

Try to keep it simple, and if necessary reference the user to other tutorials that cover the topic in isolation, like:

This is where we'd write validations to avoid receiving wrong data, you can read this other tutorial to learn more about validations in NodeJS, but since this is a GraphQL tutorial we will not cover it here"

3. Don't throw libraries to soon

Unless your tutorial is about a library, don't use it from the beginning. Like I'm starting to learn GraphQL and in my first tutorial they start using Apollo, and GraphiQL.

By using libraries and helpers to soon, you run in the possibility of your students associating both concepts as one, like I can assume from this experience that the way to write a GraphQL server is through Apollo, and every time I'm using GraphQL I have to use Apollo.

I'd recommend to always start teaching something with te minimum necessary to make the technology work, you know, that famous "Hello world" example, without using libraries, complex examples, analogies or anything that you'd not consider part of the technology you're introducing.

4. Organize your content as atoms

This is one of the most important things I've learnt while building CódigoFacilito, separate your knowledge in a way I can search it independently.

This is basically the same advice from point number 2, instead of throwing everything you need to make a real world example, separate everything in independent tutorials or use the content that already exists in the internet.

For example, instead of teaching Express, validations, ES2019 in the same GraphQL tutorial, write one article for each and reference them in the GraphQL tutorial

Here I'm using some ES2019 features, you can learn more about it in this other post"

If you don't know how to write an Express server, I'd recommend you to read this other article first"

This would help your audience read or watch your content independently from their level of expertise. Beginners will be able to read the fundamentals before the tutorial, and Experts will only read what they need instead of receiving an introduction to everything in every post

Conclusion

Teaching is hard, as it's teaching programming. I encourage every single person to teach because as experts can give their expertise, beginners can give their perspective of a technology from someone who is new to it, to someone who is some steps behind.

=====

At CódigoFacilito we teach spanish speaking students how to start with programming, web development, mobile development and other skills they need to succeed, and although we produce lots of free content, we also have a $9USD/month membership (or $90 yearly) for Premium content, if you'd like to sponsor a membership for someone that can't afford it, please let us know at uriel@codigofacilito.com