Plan for merging the MDN curriculum with the MDN learn web development area

[chrisdavidmills]

Notes for translators

Because of the scale of the changes that this work has made to the en-US site, there will be some challenges in updating the translated equivalents.

• You can expect to see about 15 or so related pages included in the conflicting directory. This has occurred in places where a topic had multiple landing pages and now it only has one. For example, the Learn/JavaScript, Learn/JavaScript/First_steps, and Learn/JavaScript/Building_blocks content now exists under Learn_web_development/Core/Scripting. The Building_blocks landing page was moved to Learn_web_development/Core/Scripting as it resulted in fewer move commands being needed, the other articles were moved under that same folder, and the other landing pages were then deleted and redirected to Learn_web_development/Core/Scripting. The pages are like to be something like these:
  • ./files/fr/conflicting/learn_web_development/core/scripting/index.md
  • ./files/fr/conflicting/learn_web_development/core/structuring_content_56f25f5ab024f40712bfcb6d2a4a419f560f3f86a2332133605f5e49a2219e4d/index.md
  • ./files/fr/conflicting/learn_web_development/core/scripting_785964b4c0711553d2bf3130baef052c6d78a03b4ce249eeb9d1ce2be1e3c308/index.md
    -./files/fr/conflicting/learn_web_development/core/css_layout/introduction/index.md
  • ./files/fr/conflicting/learn_web_development/core/styling_basics_fa344166552fbe2c038b1254d9d96dc0de5d79eb64d0ca3e5784a17f79fd0333/index.md
  • ./files/fr/conflicting/learn_web_development/core/structuring_content/index.md
  • ./files/fr/conflicting/learn_web_development/core/structuring_content/html_table_basics/index.md
  • ./files/fr/conflicting/learn_web_development/core/styling_basics/basic_selectors/index.md
  • ./files/fr/conflicting/learn_web_development/core/styling_basics/what_is_css/index.md
  • ./files/fr/conflicting/learn_web_development/core/styling_basics/index.md
  • ./files/fr/conflicting/learn_web_development/core/styling_basics/getting_started/index.md
  • ./files/fr/conflicting/learn_web_development/extensions/forms/index.md
  • ./files/fr/conflicting/learn_web_development/extensions/testing/index.md
• In most cases, it is fairly obvious where modules have been moved to:
  • Learn/Getting_started_with_the_web -> Learn_web_development/Getting_started/Your_first_website
  • Learn/HTML, /Learn/HTML/Introduction_to_HTML, Learn/HTML/Multimedia_and_embedding, Learn/HTML/Tables -> Learn_web_development/Core/Structuring_content
  • Learn/CSS, Learn/CSS/First_steps, Learn/CSS/Building_blocks->Learn_web_development/Core/Styling_basics`
  • Learn/CSS/Styling_text -> Learn_web_development/Core/Text_styling
  • Learn/CSS/CSS_layout -> Learn_web_development/Core/CSS_layout
  • Learn/JavaScript, Learn/JavaScript/First_steps, and Learn/JavaScript/Building_blocks -> Learn_web_development/Core/Scripting
  • Learn/Tools_and_testing/Client-side_JavaScript_frameworks -> Learn_web_development/Core/Frameworks_libraries
  • Learn/Accessibility -> Learn_web_development/Core/Accessibility
  • Most other stuff was put under Learn_web_development/Extensions
• There are a few cases where individual articles may have been moved to unexpected places. If in doubt, just ask.
• The landing pages are where you'll see most content-level changes, including new structures and different lists of articles. The individual articles are mostly not changed very much, except to change the previous/next links as required and change some descriptive text where it has bene made incorrect by the restructuring. This text includes text of the type "In the next article we'll cover blah blah..."

Summary

Moving forwards from now, into 2025, The Mozilla MDN team is planning to restructure the MDN information architecture, top-level navigation, documentation source, and some of the content. This work aims to make MDN content more consistent and easier to navigate, reduce repetition, improve MDN’s SEO/search rankings, and enable the community to contribute more easily to MDN. Ruth John is leading this plan; she previously shared some of these ideas in previous community gatherings (such as her content workshop) and will share more about it when ready.

A significant part of this plan is merging the MDN Curriculum with the Learn Web Development content (aka The Learning Area, or Learn). This discussion summarizes the history of the two content sections, explains their current issues and the rationale behind the merger, and outlines the phased plan for carrying out this work.

I would love to hear your thoughts on this plan.

History of learning content on MDN

MDN’s core target audience has traditionally always been professional web developers who want to look up reference content and techniques to help them do their job (also, we have traditionally focused on the front end).

However, around 2015 this started to be seen as a problem. We noticed that MDN was being recommended as a great resource for experts and non-experts alike, but it was not suitable for beginners wanting to learn web development fundamentals. We saw several blog posts, forum posts, and comments online from aspiring web developers who found MDN frustrating, and too hard to use. We wanted to change this and make MDN more usable for people at any level of experience! We also really wanted to tap into the “non-expert”/beginner market.

To this end, we began many initiatives, one of the most significant of which was Learn (another good example is the interactive examples you see at the top of HTML, CSS, and JS references pages).

Learn was first launched in mid-2016, to take beginners from “beginner to comfortable”. After working through the learning area, readers should know enough to comfortably use the rest of MDN. It was pretty successful — at peak usage, around 2019-2020, it boasted around 3.5–4 million page views per month; a little under 10% of MDN Web Docs’ monthly web traffic (source: Introducing the MDN Web Docs Front-end developer learning pathway).

The previous link also introduced a new Learn feature — a front-end developer learning pathway to help readers navigate all the Learn content. It suggested an order to work through the Learn articles in, along with helper material, time estimates, etc.

However, the pathway was hastily put together and wasn’t really all that useful. It didn’t feel like a true learning pathway, more like an alternative landing page for Learn.

To improve on this situation, we decided to create a properly structured learning pathway, and the MDN Curriculum was created after much research and consultation with many different target audience members (for more on the rationale behind the curriculum, see this discussion). It officially launched in early 2024. Initially, there was a great deal of interest in the project, particularly from educators, who loved having an official curriculum recommendation from a respected industry voice that could be used as the structure of courses, certifications, etc.

Issues with MDN Learn and Curriculum

All the above said we can significantly improve the learning content available on MDN.

Learn’s user base has decreased in the last couple of years:

Graph to be inserted illustrating the decline of Learn usage; numbers still TBD

There are several reasons that we suspect to be behind this:

• There is a lot of high-quality beginner’s learning content now available on the web, more than there was a few years ago, some free and some not.
• MDN and its contributor base produce great textual content (references, guides, tutorials), but do not have the skills, resources, or infrastructure to produce video/interactive content. Beginner learning audiences, especially the younger generation (e.g. GenZ) are increasingly interested in learning via non-textual content, which puts MDN at somewhat of a disadvantage.
  • This is a good reason to look at partnerships with other content providers who provide interactive content.
• Learn was first created with the best of intentions — teach beginners front-end fundamentals, and keep the scope small — but as time has gone by, Learn has become bloated, more complex, expanded scope, and not as suitable for beginners. In short, it has become more like the rest of MDN!
  • We have had feedback from users complaining that the Learn content is too hard (see an example here).
  • Effective beginner’s learning content needs to assume less knowledge and have a lower information density.
• The rise of AI has led to many people finding answers using AI shortcuts such as GitHub Copilot or ChatGPT, rather than searching for answers themselves.

The Curriculum has also suffered a decline in interest since its launch:

We have some ideas as to why this is, based on conversations with our users, community, and partners:

• The name “curriculum” appeals to educators/academics, but it is somewhat meaningless to many learners, who just want to find some effective learning tutorials.
• Having the curriculum separate from Learn was originally done because a) we wanted to ensure that the content was changed rarely so the learning objectives were kept stable, and b) we wanted to experiment with embedding partner content to strengthen our capabilities, as well as look into alternative revenue streams such as partner affiliate revenue. However, that separation is confusing. Users are not sure why there are two different resources for beginners, and which one they should choose.
  • This means we are cannibalizing our own page views, and harming SEO.
• The curriculum structure itself is more useful for educators/academics who want a pure syllabus to base courses on, but not as useful for actual learners. Learners don’t want to have to find their own resources to learn — they just want to be spoon-fed an effective course.
• Putting the curriculum in a separate place that cannot be contributed to by the community means we cannot get help with the content from other parties, and it doesn’t feel great from a community togetherness perspective. It would be better to work on this together, provided we can control the flow of edits to the content to keep the learning objectives stable and make sure the articles still teach it effectively.

Merging the two

Considering the issues highlighted above, we’ve concluded that we should merge the curriculum back into Learn. This would immediately:

• Result in a single unified location for beginners to go to for learning web development fundamentals, thereby reducing confusion and stopping the cannibalization of page views.
• Give the content a more intuitive name so it is more obvious to find for learners.
• Put the learning content together with the learning objectives, side by side, lowering the barrier to learners accessing the content they need to learn.
• Bring the curriculum back into the main MDN content source, allowing the entire community to contribute.

How would we achieve this? There are many aspects of this plan to be considered, which we will touch upon in the sections below.

Update the learn landing page

We should update the current Learn landing page to be more similar in style to the Curriculum landing page, to make it less academic-looking, and brighter and more attractive to beginners.

This wouldn’t happen immediately. It would require some design and dev work to make such implementations possible. We are thinking about creating a system to allow customized landing pages anyway, to make MDN more attractive and approachable, and result in more effective user experiences and discovery of content.

In the short term, the goal would be to make the text more approachable and beginner-friendly. We will be as bold as we can given the current platform constraints.

We would have to change how we:

• Talk about the content goals and structure. We intend to present the Learn content in the same way as we do the curriculum modules — Core for fundamentals, extensions for other content, etc. — but we would have to do so in a way that works for Learn.
• Handle promotion of partner content. In the new world, Learn will be an effective solution for learning the objectives currently set out in the curriculum, so partners will be somewhat sidelined. However, we still believe they are essential for providing interactive/video experiences, which MDN doesn’t have the capabilities for (see Consider partner content embedding below for more).

We should create guidelines for landing pages, which may or may not start with this project.

Restructure Learn

In general, Learn will require quite a bit of restructuring. As mentioned above, the modules will be grouped in the same way they are currently in the Curriculum, with the Core modules providing “topics that we feel every web developer should have a good grounding in”, which can be used as a basis for other courses, entry-level certifications, etc.

Other modules outside this would be put in the “Getting started” or “Extensions” module groupings, again, the same as the Curriculum.

Some of the existing Learn content isn’t suitable for beginners to web development, and will eventually be moved out to Learn “extensions”, or separate MDN topics in their own right (for example, performance, automated testing, and MathML do not constitute essential topics for beginners to know).

The module landing pages will need a content and style update to include the learning objectives from the curriculum alongside existing useful content. We will also need to consider a title/slug change to mitigate SEO issues. For example, search engine confusion between the regular MDN HTML landing page and the Learn HTML landing page could be addressed by retitling the Learn page to something more task-based, such as “Structuring web page content”?

Initial work will require an audit to make sure the curriculum modules are suitable for acting (at least in part) as landing pages for the learn articles, and making adjustments as necessary.

Make Learn content more suitable for beginners

Eventually we want to edit the Learn content to make it more suitable for beginners — sparser, lower information density, assume less knowledge.

We will also consider creating some new content to provide excellent coverage of existing Curriculum topics that MDN doesn’t currently handle very well, for example Soft skills, Environment setup, Web standards. In the short term we will probably just link to external resources.

Consider pathway navigation

Effectively, we intend to turn the entire Learn section of the site into a structured learning pathway, which is what the Curriculum was aiming to provide. The Learn section already has structured navigation (previous/next links) between different articles in the same module, as well as links up to the module index at each point.

We need to make sure that this navigation works for the new state of Learn and for the entire pathway (for example, navigating to the start of the next module when the previous module is finished).

Consider external/partner content embedding

Learners (particularly those in the younger generation, e.g. GenZ) increasingly favor short-form interactive/video content, which is an area that MDN does not currently have the capabilities to produce.

As part of the Curriculum work, the Mozilla MDN team has developed a custom element for embedding external partner content. We should consider modifying this to work on the main MDN content and agree on a plan for embedding interactive/video content on Learn pages to enrich the text-only content and make it more attractive to users.

This would also allow us to continue experimenting with partner affiliate revenue streams to help fund MDN and improve it further.

Create guidelines for editing Learn

One concern, which originally provided the rationale for putting the Curriculum in a separate place, is that a structured learning pathway should have stable learning objectives, which change very slowly and only with good reason. This is especially important if you are providing a curriculum that others can base their courses on, and which can be used as the basis for a certification.

To this end, we will need to provide guidelines to follow for those wishing to edit Learn. Small edits should be OK, provided they don’t affect the teaching of the learning objectives contained within each module, or change the learning objectives themselves, particularly in the core modules.

We should also include:

• Guidelines around what constitutes a suitable topic to add to the Learn section.
• Guidelines on where to put content deemed not suitable for Learn: the new plan will includes places for tutorials and guides in regular MDN topic areas.
• A statement defining what the remit of Learn is. We originally envisaged it as being a place to publish beginner-level content for readers to learn the fundamentals of web development. Others seemed to think that it was the place on MDN where you publish learning content in general — including more advanced tutorials, etc. But we never stated the remit explicitly, which is in part how Learn got into its current state.

Other solutions considered

• Merge Learn into Curriculum: We also considered doing the move in the opposite direction, but this made considerably less sense, both in terms of community togetherness, and logistically — a lot more content would need to be moved if we were to attempt this route.
• Just get rid of Curriculum: We considered this briefly, but there is a lot of value in the work that has gone into the Curriculum and the approach that it takes. It forms the basis of a dedicated, structured beginner’s learning experience, which is really what the Learn section should have been from the beginning.

The plan: Phases and timeline

The above work is substantial and needs to be split into multiple phases. Our current thinking behind the phases is detailed below.

Phase 0: Planning and discussion

• By October 24, 2024: Create a spreadsheet that includes the proposed new structure of Learn, which includes details of which Curriculum content will be used where, which Learn tutorials will be put where, and what changes are needed as a result. The learning module pages should be structured by learning objectives — it is vital that each module includes content (or external linked content) that teaches the learning objectives.
  • This is done and can be viewed on request.
• By October 25, 2024: Post a public version of this plan summary to raise awareness and get feedback from the community
  • Done: This is this!
• By October 28, 2024: Create an MDN content pull request that includes updated pages (main landing page, couple of module landing pages, etc.) that provide a glimpse of what the new structure might start to look like, to help people as they evaluate the plan. This will also help me uncover any issues I might not have already thought about.
  • This has already been started: see the draft at Draft PR for merging MDN Curriculum into Learning Area content#36502.
• On October 28: Talk about the plan in the next MDN Content Call. Give people a week to provide feedback.
• By November 6: Hopefully address feedback and concerns sufficiently so that we can start on Phase 1 of the Learn update. Controversial topics (such as embedding of partner content) can continue to be discussed during Phase 1 implementation and hopefully be resolved so that we can start on them later on.

Phase 1: Initial update of landing pages and navigation

By November 25: Update the Learn content and navigation to complete the initial merger of Learn and Curriculum.

This includes:

• Updating the main Learn landing page.
  • We intend to update the /learn slug to /learn_web_development
• Updating the module landing pages to reflect the new task-based titles/slugs and include the curriculum learning objectives.
• Moving any “easy-win” content (such as MathML guides) out of Learn and into their respective topic areas.
• Publishing guidelines for editing Learn (see Create guidelines for editing Learn)
  • See draft at https://docs.google.com/document/d/1pGaljbZcjPOYB0sjJ4r-Ba_GN4oW8RKpCm5ILXaz_cI/edit?tab=t.0
• Putting required redirects in place
• Updating the sidebar and in-article navigation to reflect the new structure.
• Updating the MDN top-level navigation as required
• Deciding on any design update requirements and:
  • Implementing the items that won’t require any dev changes
  • Leaving items that do require dev changes till later on.

This does not include:

• Moving all unsuitable content out of Learn; some will require more thought and reorganization. For the moment, most of the unsuitable content will be placed as extensions.
• Significantly updating Learn articles. This will be done in a future phase.

Phase 2: Move unsuitable content out of /learn_web_development

This will start to be done probably in phase 1, but completed in 2025.

Phase 3: Update core learn_web_development content

This will start to be done in 2025.

[meyerweb]

The rationales and goals are laid out well, and I see where and why you intend to go with this. I would quibble that performance is actually a topic beginners need to know about, but perhaps it’s the case that they should learn about it differently than MDN currently addresses it.

One question occurred to me, related to “Consider external/partner content embedding”. Will this provide tools/hooks to embed non-partner content, such as a particularly good YouTube explanation of the Popover API or a short video explainer on how CSS animation and transitions differ?

Also, there’s still a TBD chart in the post; not sure if that was meant to be replaced before publication, or was left there so as not to hold up publication for one chart.

[chrisdavidmills]

The rationales and goals are laid out well, and I see where and why you intend to go with this. I would quibble that performance is actually a topic beginners need to know about, but perhaps it’s the case that they should learn about it differently than MDN currently addresses it.

Thanks @meyerweb! I don't disagree that performance is important for beginners to grasp, but I do think we need a different approach for beginners — probably including it throughout the core content in appropriate places, rather than having a single module that dives in deep. For the moment, we will probably end up keeping what we currently have as an extension, and develop it further later on.

One question occurred to me, related to “Consider external/partner content embedding”. Will this provide tools/hooks to embed non-partner content, such as a particularly good YouTube explanation of the Popover API or a short video explainer on how CSS animation and transitions differ?

Potentially yes. This is worth discussing more.

Also, there’s still a TBD chart in the post; not sure if that was meant to be replaced before publication, or was left there so as not to hold up publication for one chart.

The latter is correct — I wanted to publish it before the end of the week.

[wbamberg]

One thing I'd really recommend is investing in tools to help learners check their progress. I think that at the time they were created, they were the best that could be done given the constraints the creators were under, but there has never since then been the kind of investment that would have been needed to improve them. And I think that's a big part of the reason beginners struggle. There's a trickle of issues from people not knowing how to do an assessment or how to check their answers.

I don't know if this is covered by "video/interactive content created by partners". To me it sounds more fundamental than "enrich the text-only content and make it more attractive to users".

[chrisdavidmills]

One thing I'd really recommend is investing in tools to help learners check their progress. I think that at the time they were created, they were the best that could be done given the constraints the creators were under, but there has never since then been the kind of investment that would have been needed to improve them. And I think that's a big part of the reason beginners struggle. There's a trickle of issues from people not knowing how to do an assessment or how to check their answers.

I don't know if this is covered by "video/interactive content created by partners". To me it sounds more fundamental than "enrich the text-only content and make it more attractive to users".

@wbamberg excellent feedback. I have considered what an effective progress checking/assessment experience might look like; I agree that what we have offered previously has been substandard. I think realistically this will be a separate, future phase.

Right now, we will concentrate on apply the new structure to Learn. In the future, we will look to:

1. Updating the assessments to something better. I could definitely see this involving content provided by partners, maybe with assessments written by us, but hosted using their tooling.
2. Providing some kind of a progress indicator/recording tool.

[Josh-Cena]

My only feedback, right now, is please kill off all the client-side framework guides that no one is maintaining, which very likely includes Vue, Angular, Svelte, and Ember (i.e. everything other than React). It's a net minus for both readers and MDN to have outdated content than no content.

[chrisdavidmills]

My only feedback, right now, is please kill off all the client-side framework guides that no one is maintaining, which very likely includes Vue, Angular, Svelte, and Ember (i.e. everything other than React). It's a net minus for both readers and MDN to have outdated content than no content.

@Josh-Cena The original reasons for offering multiple framework guides were to offer alternatives to just React, and try to seed the idea that you'll be expected to use multiple frameworks. But I agree that the lack of maintenance is a problem, outdated content is harmful, and it is also more confusing than it helps to offer beginners too many options.

I think initially we will just rearrange the articles, and then in a future phase, we will decide what to deprecate. I suspect we will keep React and Svelte (to offer an alternative, plus the Svelte docs are about to be updated).

[Elchi3]

Consider external/partner content embedding

Would be good to update https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/What_we_write and https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#external_links (or create a separate page) to give mdn/content contributors guidance on partner embedded content, affiliate links, etc. and how such things are governed. If these are custom elements, then I guess it might be as straightforward as documenting said custom elements, how contributors should (or should not) make changes to them, and how reviewers should handle PRs that propose changes. By having clear policies, we could likely avoid discussions similar to the polyfill situation and reviewers would know what to do and which policies to refer to. I think this was easier to control when the content was in https://github.com/mdn/curriculum but now that it merges with the main mdn/content repo, giving the larger contributor community guidance and policies around this topic feels like a necessity to me.

[chrisdavidmills]

@Elchi3 Yes, I entirely agree. Thanks for the useful thoughts on this, Florian.

[chrisdavidmills]

The discussion above is largely closed; there doesn't seem to be much else in the way of new discussion. We have moved ahead with the restructuring and it is nearly ready to publish (see mdn/content#36967), and we are planning on actioning all the points that were brought up above.

Syncing translations with the en-US changes does bring up some challenges. I will add some notes on that above — see the top of the original discussion text.