The team behind the MDN, formerly started as the Mozilla Development Network, announced plans to move the documentation site on the Mozilla Hacks web developer blog and published the first beta of the new platform. A GitHub-based approach replaces the previous Wiki.

The MDN team obviously has a certain sympathy for Pokémon.

(Image: Mozilla Hacks)

The new platform bears the code name Yari as a reference to the traditional Japanese lance. The blog post compares the development of Pokémon with the change from the previous Kuma base to Yari. In the games, the development is often more of a metamorphosis, in which the appearance and sometimes the skills change significantly. Obviously the MDN team has been planning a “radical change of the platform” for a long time.

The beta form of Yari The major upheavals only affect the backend. For users of the documentation, however, the change should be made relatively transparent. The changes will affect those who develop the platform on the one hand, and the authors of articles on the other.

Yari’s first beta has been on GitHub since November 3rd. Developers can test it out, and the blog post says the first release is firm for the 14. December planned, which already suggests a stable state of the software at the beta start.

Motivation for the change The team names four main reasons for the changeover of the platform: Less administrative effort for the development side, better workflows for contributors, expanded involvement of the community and an improved front-end architecture. In addition, the job cuts at Mozilla in August, which were also associated with the downsizing of the MDN team, should have given an additional boost.

Obviously, it is quite difficult to add new functions to the Kuma platform expand. With Yari, a large part of the code base should disappear and thus the management of the project will become much easier.

Pull requests instead of Wiki The model is geared more towards the processes that software developers are used to: In the future, content contributions will be created similar to code submissions for open source projects in the form of Pull requests (PR) instead of direct changes in the wiki. In addition, processing should be able to be integrated into typical processes and MDN source files should be conveniently processed in development environments.

The PR approach means that the publication is preceded by a review process. This means that the MDN team has a look at the posts and can provide additional feedback before new content goes live and potentially has to be changed afterwards. This promises a stronger bond with those who regularly make content-related contributions – analogous to the communities of open source projects.

When checking changed or new contributions, additional tools for quality control can be integrated like automatic test tools to better ensure that code is correct. At the same time, the frontend is to be revised, which currently has weak points in some areas.

JAMstack instead of Wiki In the old model, all clients access the content via a content delivery network (CDN), regardless of whether they are only calling up articles or creating or editing them. At Yari, the creation of posts takes place on GitHub. The architecture also separates the delivery of documents from search queries and account-specific traffic. As before, the latter services are located in their own Kubernetes cluster, which is, however, much smaller than before.

Architecturally, Yari relies on a JAMStack where the first three letters stand for JavaScript, APIs and markup. In terms of architecture, the system delivers statically generated websites, and the dynamics take place via the APIs or serverless functions. The rendering of the web pages does not take place with every client request as with server rendering, but in the course of the page build process.

The new platform separates contributors from readers and is intended to handle the delivery of documents speed up the CDN.

(Image: Mozilla Hacks)

The old platform read the content from a MySQL database, converted it to HTML and delivered it via a CDN, where it was cached for five minutes to enable the same queries without database access. In the new model, the content goes daily to an S3 instance on Amazon Web Services, which delivers it to the CDN for reading. Version management Git plays an essential role in the ecosystem for creating content.

Detour via the IDE Contributors may initially need to get used to the changeover. You can no longer edit content by simply clicking on Edit edit the page in a WYSIWYG editor, but have to fall back on the processes and tools used in software development.

Typically, you create new contributions in a development environment or a source code Editor like Visual Studio Code and then submit it as a pull request in the GitHub repository. For simple code changes you don’t necessarily have to go through local tools, but can edit the adjustments via the GitHub UI.

To start, those who write contributions have to edit all files in the HTML source code . This includes checking the output in the browser before submitting the PR. In the long term, however, the team is planning to switch to Markdown as the standard format for the content.

Further details on the process and the infrastructure can be found in the blog post on Mozilla Hacks.

(rme)