Here's how to keep docs up to date

[AMDphreak]

Mozilla needs to create a tool that automatically tells authors what docs need to be updated.
To do this, you guys need to use a tool for mapping the dependency between the old features and new features. If new feature B and new feature C impact old feature A, then this change should be recorded in a dependency graph, and the graph should be consulted by a script that checks docs for references to the old feature, and marks them as out of date.

Also, the docs should be preserved for each iteration of ECMAscript (except bug-fixes within the same major release).

For example,
This doc page uses examples containing var, however its parent page uses let and const. Reading docs that arbitrarily jump back and forth between the two features, while learning Javascript, is really confusing. var is effectively a dead feature and really should have been removed from Js altogether, so those examples are doing nothing but prolonging a systemic problem in the software industry.

If someone submits a page, and another page links to that page, then the author of the page and the parent page/s (applied recursively) should both be notified.

Example email:

Subject: Mozilla Developer Network code update request
Message body:

ECMAscript (the Javascript standard) has been updated to version [current version number].
The document you contributed to uses examples that are no longer in compliance with the Javascript ECMAscript standard.
[title of document with hyperlink]
Please update this document to reflect the most recent changes in ECMAscript:
Features that need updating:

• [link to A] has been replaced by [link to B] and [link to C]
• [link to D] and [link to E] have been replaced by [link to F]

An archived copy of the document for ECMAscript version [old version number] can be found here:
[title of document with hyperlink]

If the page is not updated by anyone, the email should recur after a few months.

[AMDphreak]

Also, instead of trying to support backward-compatibility in ECMAscript, you should tell the ECMA group to invest in creating well-designed official tools for Javascript developers that does the same thing as this script. It should look at their code and provide updated algorithms for anything that can be replaced, and point out patterns that must be refactored by hand; for example, the uses of var that can actually can't be replaced by let or const because they utilize the var feature in an intentional way.

If ECMA invests in this strategy, they can finally get rid of the backward compatibility. ECMAscript needs to force the web dev community to adopt better practices. Being laissez faire about how ECMAscript should be used is a recipe for confusion for new programmers. It is also a huge waste of time for new web programmers to have to learn all the different versions of Javascript. I don't want to learn 100 dialects of any language.

[teoli2003]

We are in the progress of updating our pages not to use var (most of the time) anymore.

See mdn/content#16614 and mdn/content#16662 that tracks part of this ongoing project.

More generally, we are in the progress of modernizing our JS examples to use a more modern syntax: #143.

MDN is such a large corpus that it takes time to update it. Now that we are on GitHub and not a wiki anymore, we are adding more toolings and can better coordinate projects that update it. We were gated by having the docs in a non-open DB (even if the code was open; Since the end of 2020 we are gated by resources, but we improve our efficiency every Quarter by restructuring MDN. Last week, we started updating fetch examples for example. Overall, with more than 10000 pages to update, this takes time; finding pages to update is not a complex part of the job.

To be more efficient, we moved to MarkDown in 2021, for example, and this year (2022) we are creating and adding page types that will help us have a more coherent structure between pages. We plan to standardize the way to present polyfills too. Each of these activities is complex and takes time, but will help us be more efficient in the mid-term.

Note that many non-Mozilla people help on MDN, so that's not only Mozilla's problem.