OWD projects in H1 2023
We're at the start of H2 and planning the projects we expect to take on next. So it's a good time to look back at the projects we completed in the first half of the year. We've blogged about a couple of these projects before and hope to write more detailed posts about some of the others, but for now, here's a relatively quick rundown.
As well as the projects listed below, we've continued our day-to-day work of supporting the MDN contributor community, by mentoring volunteers and reviewing PRs.
The great renaming of Web/API
This year we finally addressed a problem with MDN's Web/API docs that has vexed web developers since at least 2018: that the titles of pages for Web/API properties and methods, like the postMessage() method of the ServiceWorker interface, were written as though they were static members of those interfaces, like ServiceWorker.postMessage().
Discussion of an acceptable alternative reached consensus in 2022, but implementing the change consistently across all 4000 or so pages only became practical after we had assigned machine-readable page types to the Web/API pages. After that, we could update the titles in a couple of days.
The retitling also enabled us to document, for the first time, Web/API static methods that have the same name as Web/API instance methods, like Response.json().
For more details on this project, see our separate post on The great renaming of Web/API.
Documenting interoperable Web/API features
At a meetup in January, someone mentioned that it would be great to have a tool to cross-check between BCD, the specifications, and MDN, to flag web platform features that have cross-browser support, but don't yet have docs on MDN.
The next day, Dominique Hazaël-Massieux came up with the mdn-gaps tool, which does just that.
This enabled us to start a project to document all Web/API features that are supported in at least three browser engines. We split this into phases:
- the first phase includes all features except those that relate to the HTML and SVG specs, that are often reflections in JavaScript of attributes in those languages.
- the second phase includes the HTML and SVG features.
In H1 we completed the first phase, adding over 100 new reference pages to MDN, including topics in such diverse and important APIs as web components, service workers, and file handling.
This project also has its own standalone post: see Documenting missing interoperable web features.
Progressive web apps revamp
Also in January, Patrick Brosset, one of the Microsoft representatives on our Governing Committee, proposed a project to update the MDN documentation for progressive web apps. MDN's docs on progressive web apps were mostly written in 2017, and were never substantially updated since.
To get an idea of what kind of content to add, we used the Divio documentation system which describes four different types of documentation, that each perform a different function. The Divio system is - we think - one of those ideas that is so useful, that when you hear it, you wonder why you never thought of it before.
We've never really used Divio on MDN, because most of our work is on reference docs only. But the progressive web apps project added mostly learning material, such as guides and tutorials, and we found the Divio system very helpful in planning our work. We added explanations, how-to pages, a new tutorial, and updated the existing reference docs where that was needed.
Patrick not only proposed the project, but helped plan it and wrote and reviewed a lot of the content.
Performance API docs revamp
This project was originally proposed by the Web Performance Working Group in 2021, and saw us completely overhauling the reference documentation for the Performance API.
The Performance API enables web developers to gather metrics about various aspects of a web application's performance, such as how long it takes for event handler to run in response to a user action or how long it takes to download and process a resource.
The existing MDN docs were incomplete and out of date, and did not present a unified view of the different APIs, or include useful guide pages.
We wrote or rewrote around 150 reference pages, reorganized the Performance API reference docs to be in a single structure, and wrote new guide pages.
Fixing BCD errors
The final project we'll highlight today was to fix errors in browser compatibility data.
The BCD project uses a tool called the mdn-bcd-collector, which tests browsers for support of various web platform features. When the results of this tool differ from the data in the mdn/browser-compat-data repository, this is sometimes a false positive, but often points to an actual error in the data.
This year, we're working on a project to eliminate these errors from the BCD repository for all browser releases from 2020 onwards. In the first half of the year we completed the main part of this work, to fix errors in the Web/API, CSS, and JavaScript sections of the data.
This gives web developers a more accurate picture of the compatibility status of a feature, whether they use MDN, Caniuse, or some other application that integrates BCD.
What's next?
We're currently planning our H2 projects. As you might see from the list above, many of our projects are those proposed by our partners and the wider web developer community. We think OWD's super power is our connections with people like Dominique and Patrick, and we're very grateful for their engagement with us in this and other projects.
So if there are content projects you'd like to see us work on, we encourage you to file a proposal, and talk to us about it. If you want to work with us on it, either to specify the work or to help with writing, that's great too!
Open Web Docs is a non-profit collective entirely funded by individual and corporate donors. We're very grateful to everyone who sponsors us. We think the projects we completed in H1, and those we plan for the future, will help web developers to build exciting applications to serve their users better. If you think so too, please consider sponsoring us, or asking your employer to.