MDN’s new design is in Beta! A sneak peek:

How to create learning pathways

Among the various tasks possible for the learning area, one of the most important is to design a learning pathway. A learning pathway is basically a set of articles to read and exercises to complete in order to learn something, usually in a specific order. However, creating good, efficient pathways requires some work; this guide will help you learn how to plan and create a learning pathway on MDN.

A learning pathway really looks like a tutorial and, yes, it's very similar. The difference is that a tutorial is the concrete result where a learning pathway is the blueprint. Let's view the details of what needs to be done in order to create great learning content on MDN.


At the beginning of designing a learning pathway, there is always a time of formulating your idea. As the designer of such a pathway you are in a position of being the teacher, so you need to formalize the lesson you're teaching. In short, you have to answer the following questions:

What do I want to teach?

It can be general knowledge (for example, Object Oriented Programing, HTML, Web Design) or a more specific task to perform (for example, How to build a web site, How to design a navigation menu). This is really up to you but it's important to stay focused. The web is quite a large beast and there are many things to learn. Try to narrow down what you want to teach in order to provide clear insight to those who will learn from your pathway.

Who's the audience?
Learning styles, and therefore approaches  to teaching, vary widely depending on who is doing the learning. If you want to teach to children, you take a different approach than when teaching adults. If you want to teach beginners, you will need to focus on basic things that could sound horribly obvious to a skilled developer. Answering that question will help you define the tone and the depth of information you need to put into your pathway.
Does it required prerequisite skills?
This is important in order to define the ease of your pathway. If your pathway has many prerequisites, it is a more difficult pathway, which means that only very skilled people can even begin it. Pathways that target beginners should have relatively few prerequisites. For example, if you want to create a learning pathway to teach WebGL, people learning from that pathway must already know JavaScript. Therefore only average or skilled web developers will be able to go into such a pathway. This is okay but it's better to be very clear about that from the beginning.

Pro tip: It's sometimes difficult to do this alone. We encourage you to share your ideas and to gather feedback. That will help you in to test your ideas and to avoid forgetting things. To do that, you can discuss all your ideas on the MDN discussion forum (to talk about technical content) and the Mozilla Learning forum (to talk about the various ways of teaching). It can also help to use simple note taking tools (such as Etherpad) to easily share and gather information.


OK, now that you know what you want to teach and to whom, it's time to define how to do it.

The first thing to do is to break the tutorial lesson into small individual pieces. Basically it's like having an image and using a jigsaw to create the pieces of a puzzle. The smaller the pieces are, the better. Once you have all those pieces, it's time to group and sort them into logical incremental groups. Iterate as much as needed to produce a comprehensive way of getting from zero to completion.

There is no magic way to acheive this. Each lesson has its own requirement and each teacher has their own teaching method. The way you want to teach something will have a huge impact on how you'll break things into smaller parts. As a reminder, for MDN, ultimately it will be about writing articles and providing exercises for people who will learn by themselves.

Also remember that there is no hard constraint on how to sort things out. If you want to build straight forward learning pathways that's fine. But if you want to build conditional pathways, that's fine too. What is important is to make things clear. You have to put yourself into the learners' shoes. Conception of a learning pathway is not very complicated but can take quite some time.

Pro tip: When going to conception, it can be helpfull to discuss things with others (as for the ideation part, see above). Since creating a learning pathway is about structuring information, it can be very helpfull to use some of the techniques that come from UX design such as card sorting. As an example, card sorting was used to figure out how to structure the "How to build a web site" pathway. It helped us break up and sort things out by producing a clear tree of knowledge.


Ultimately once you get a clear view of the pathway itself, it is important to start defining the type of content needed for each step of the pathway. On MDN, at a minimum there should be a learning article. Such articles can be associated with various active learning content (basically: exercises). Of course, you can also imagine other types of content such as videos, assessments and tests to validate knowledge, etc.

Once you are clear on those various content requirements, you are ready to shape you pathway on MDN. This is very simple create a new landing page for your pathway under /Learn/tutorial. This landing page must clearly state what the reader will learn as well as any prerequisites necessary to follow that pathway. It also must contain the full list of articles to read with an excerpt for each article. Active learning content can also be listed here but it's not mandatory if they are linked directly inside the related articles.

Once the landing page is ready, it "just" requires creating the necessary content. For that, you have two options:

  • Do it yourself (beware, it can take a long time)
  • Engage people in order to help you. To do that, join the Learning Area community (see the topic box below) and explain by any means possible about what you are doing in order to find help. Welcome to MDN :)

Help the 'Learn' documentation project…
Topic driver : Jeremie Patonnier (IRC nickname: Jeremie)
Look at the current status of the 'Learn' documentation.
Don't hesitate to contact us on #mdn or on the dev-mdc mailing-list:

Document Tags and Contributors

 Contributors to this page: jswisher, Sheppy, hbloomer, Jeremie
 Last updated by: jswisher,