Open Web Docs Impact and Transparency Report 2022

2023-03-08 - Open Web Docs staff - RSS feed

Executive summary

Open Web Docs (OWD) is an open source collective that employs technical writers to publicly document open web technologies. OWD currently employs 4 full time writers and one part time writer, all of whom have extensive experience with Web standards documentation and MDN Web Docs. The OWD team writes new documentation, updates existing documentation, and improves documentation infrastructure together with other organizations such as Mozilla, Google, or Microsoft, W3C, and external contributors.

Open Web Docs’ main focus has been contributions to MDN Web Docs, the premier platform for Web platform documentation.

In 2022, OWD writers were the main contributors to MDN Web Docs.

What is MDN and why does it matter?

In 2022, OWD staff primarily worked on improving and extending MDN Web Docs.

MDN is a website documenting front-end open web technologies, in particular JavaScript, CSS, HTML, HTTP, ARIA, SVG, MathML, and the JavaScript APIs available in web browsers.

MDN is the top destination for developers to learn about web technologies. It's not just a popular website for web developers, it is an essential tool that they consult on a daily basis in their work. It provides value to all organizations that depend on the web to any extent .

MDN content maintenance

The MDN Web Docs website requires important ongoing maintenance and updates of both its infrastructure and its content to continue serving the million of web developers that use it each month.

While the website's infrastructure is maintained and improved by Mozilla, the content is operated as an open source project and receives contributions from OWD, Mozilla, Google, Microsoft, W3C, and other organizations, as well as thousands of external contributors each year.

The web platform is big and constantly evolving: MDN contains over 11,000 pages, and the content needs ongoing updating and maintenance as new web platform features are introduced and best practices change.

Among these groups, Open Web Docs has been the primary maintainer of MDN content for the last two years.

Reflecting its reach and importance to developers, the main MDN content repository, https://github.com/mdn/content, is one of the most active repositories on GitHub. According to https://git-pulse.github.io/snapshots/, it has:

In 2022, 8231 pull requests (PRs) were merged to the mdn/content repository, from 1693 contributors (excluding bots).

The main organizations contributing pull requests were as follows:

OWD Mozilla W3C Other
1211 614 258 6148

PRs merged to mdn/content 2022 by origin

This tells us that OWD contributed twice as many PRs as any other organization, and that "Other" was by far the biggest category.

The "Other" category is mostly individual volunteers, although it also includes some technical writers sponsored by other organizations to contribute to MDN. There's a very long tail of MDN contributors: 1293 of MDN contributors in 2022 - about three-quarters of the total - had only one merged PR in the year. However, MDN also has several extremely active volunteer contributors who make a big difference to the site.

Supporting this volunteer community is a major part of OWD's work. Sometimes this support consists simply of responding to PRs with review feedback, but the OWD team also plays a more active role, by leading projects in which we define what has to be done and breaking down tasks into manageable pieces, which are then implemented by volunteers. For example:

In this way OWD acts as a force multiplier for the MDN project.

One way to measure OWD's impact is to look at reviews of pull requests (PRs) authored by the volunteer community.

PR reviews for the mdn/content repository are performed by members of the maintainer group, which consists of OWD staff, Mozilla staff, W3C staff, and a select group of volunteer maintainers. Of the 7289 reviews of PRs from volunteer contributors that were merged to mdn/content in 2022, the review breakdown is as follows:

OWD Mozilla W3C Other
4831 744 1083 631

Reviews of volunteer PRs merged to mdn/content 2022 by origin

In other words, OWD performed 2/3 of all reviews of PRs from the volunteer community.

Browser compatibility data maintenance

The mdn/browser-compat-data project is the second biggest part of MDN, after the content itself. This project maintains machine-readable data about browser support for web platform features. This powers the MDN website as well as other tools like Can I use, Firefox Developer Tools, and VS Code.

In 2022, 2291 pull requests were merged to the mdn/browser-compat data repository (excluding bots).

The main organizations contributing pull requests were as follows:

OWD Mozilla W3C Google Other
678 771 86 246 510

PRs merged to mdn/browser-compat-data 2022 by origin

This shows that contributions are roughly split equally between OWD, Mozilla, and everyone else.

Not visible in this view is the massive contribution of Vinyl Da.i'gyu-Kazotetsu, who alone was responsible for more than half the total contributions to the project. Vinyl is employed by both OWD and Mozilla, so we have simply split her contributions between the two organizations in the numbers above.

PR reviews for the mdn/browser-compat-data repository are performed by peers and owners of the project, who are listed in the project’s governance document.

Of the 990 reviews of PRs from volunteer contributors that were merged to mdn/browser-compat-data in 2022, the review breakdown is as follows:.

OWD Mozilla W3C Google Other
536 390 13 48 3

Reviews of volunteer PRs merged to mdn/browser-compat-data 2022 by origin

Again, Vinyl Da.i'gyu-Kazotetsu was responsible for more than half of all reviews, and again, we have split her contributions between the OWD and Mozilla.

MDN projects

This section focuses on some of the projects led by OWD in 2022.

We're proud to have been able to carry out these projects and think they make MDN an even more valuable resource for web developers.

JavaScript code sample modernization

JavaScript has changed dramatically in the last 10 years, especially with the 2015 update known as ES6.

MDN contains thousands of JavaScript code samples, and many areas had never been systematically modernized. This meant that a great many examples on MDN contained coding practices that are now considered unreliable, hard to read, or inefficient.

Having up to date code samples demonstrating modern best practices is important because it means people will learn good practices, will teach each other good practices by citing MDN, and will incorporate good practices into their code when they copy MDN code samples.

In 2022 Open Web Docs led a project to:

Because the updates needed could be clearly defined and easily parallelised, it was a very good fit for a community-powered project, and most of the actual updates were made by volunteers. However, the project was led and coordinated by OWD staff and would certainly not have happened without their involvement.

In all:

There is still work to do here: for example, this project was restricted to the core JavaScript language and did not address browser APIs. However, this project has made MDN a much more useful resource.

Performance APIs

A group of Performance engineers participating in the Performance API W3C Working Group spent time to review and to report opportunities for improvements in MDN’s Performance docs.

We have taken this feedback and created a project to revamp about 150 reference pages that belong to this family of APIs that measure performance of websites and web applications. Over the years, many new innovations like Performance Observers, User Timing, LCP, Server Timing, etc. have been added. These concepts were presented on their own, but weren’t integrated into a single Performance API documentation set to paint a holistic picture of how to measure performance using these features. The Performance API page now presents all of the different Performance API modules in one place and gives a better overview to developers of what can be measured and how.

The introduction of Performance Observers has been key to this family of APIs. So, much like you’d expect the use of Promises in JavaScript docs these days, we have modernized the Performance API docs to talk about Performance Observers. At same time we clearly marked features of the old Performance APIs as deprecated or deleted content for removed APIs entirely.

In 2023 we’re aiming to finish this project by updating the guide pages that live next to the Performance API reference pages.

Interop 2022

Interop is a cross-browser initiative to address important web platform interoperability features. Browser vendors all implemented the Interop 2022 priorities they agreed upon. The OWD team took a leading role in ensuring that all the new and updated features were documented. Projects included:

MDN has been documenting features for many years. Some features are fully supported in all evergreen browsers thanks to Interop 2022 and other efforts, but the documentation predating full support still mentioned “when supported”, “Internet explorer”, and outdated terms like CSS3 and HTML5. Our team eliminated outdated references, updating documentation for all Interop 2022 focus areas to reflect full support and include updated code examples.

Integrating W3C specifications into MDN

MDN's CSS documentation shows web developers the syntax of CSS properties using a notation from the W3C specifications in which the features are defined. This is an essential feature of MDN, as it provides a precise description of property syntax. However, MDN maintained its own copy of the property syntax, which had to be manually synchronized with the specifications. As a result of this, the content on MDN was frequently out of date.

W3C has a tool called webref, which scrapes the specifications and presents some of their content in a machine-readable format. In 2022, OWD staff integrated webref into MDN as the source of CSS syntax values. This means the property syntax is always kept in sync with the specifications, and developers will no longer see outdated information.

We also updated the code that renders property syntax on MDN pages to make it more readable, adding pretty-printing and syntax highlighting. This means that a CSS property whose syntax used to look like this:

background property formal syntax before improvement

...now looks like this:

background property formal syntax after improvement

These two changes - more accurate content, clearly presented - make it much easier for web developers to work with CSS.

This project greatly benefited from OWD's close connections with W3C. While it serves the users of MDN, it also enables OWD to provide feedback to W3C on how they can make specifications more accessible.

Write the Docs

In May, OWD hosted a session at the Writing Day during the Portland 2022 edition of the Write the Docs conference. Write the Docs is a conference for people involved with all aspects of documentation, including writers, developers, editors, information architects and more.

For the Writing Day OWD prepared a project to remove var from code samples in the JavaScript documentation on MDN, replacing it with const or let as appropriate. We were joined by about 20 volunteers, most of whom had never made a GitHub pull request before. With our help, volunteers removed var from 254 pages in the JavaScript reference.

Eventually, this project turned into a much larger project to modernize all MDN’s JavaScript code samples across the whole site.

Shared investment is lasting investment

From end-user applications to developer tools to new APIs, developing for the web platform relies on access to accurate, vendor-neutral information and how-to. Thanks to the generous support of our steering committee participants and funding partners, Open Web Docs has:

These investments have not only helped developers learn and adopt web technologies; they have also helped countless organizations build more modern, secure, and performant products and services.

2022 Budget Recap

OWD is very grateful to its Platinum Members Google and Microsoft, Gold Members Igalia and Meta, and Silver Members Canva and JetBrains for their membership in 2022. Since its inception in January 2021, Open Web Docs has raised $1.8m from nearly 200 individual and organizational supporters. OWD’s annual operating budget is $800k.

Payroll is Open Web Docs’ only meaningful expense. OWD employs four full time technical writers and one part time contractor. Employees are paid competitive salaries in their local currency, and receive health care and other regionally compliant benefits. In 2022, OWD spent a total of $777k on payroll, contractors, transaction fees and minor operating expenses. We post all transactions on our Open Collective page.

Our sponsors have invested significantly in engineering resources to optimize and improve their browser platforms, which are built on the open web. OWD tests and documents these innovations so that they reach the widest possible number of consumers, saving vendors the cost of maintaining separate sites and reinforcing the value of our shared investment in the web. Platinum sponsors also participate in the governance of the project and help set OWD’s project roadmap and priorities.

For 2023, $500,000 has been committed by platinum sponsors Google and Microsoft, $40,000 has been verbally committed by Gold and Silver sponsors, and $10,000 is anticipated to come from individual open collective sponsors for a total of $550,000.

Gratitude for our Individual Supporters

Our individual supporters have helped raise nearly $20k for better web platform documentation since 2021 - we are beyond grateful to:

Looking forward to 2023

In 2023, OWD is excited to continue to work very closely with Mozilla on MDN Web Docs. At the end of 2022, Mozilla and OWD created a shared and open roadmap for ongoing and planned work. The new shared roadmap will foster an even more active collaboration between OWD, Mozilla, and the rest of the MDN Web Docs community. It will also create more opportunities for OWD to provide inputs on crucial topics such as: MDN's information architecture, compatibility data, code example, and other changes coming impacting all sections of the MDN Web Docs site.

Within Open Web Docs’ Steering Committee we will continue to plan and execute projects on a quarterly basis. We’re inviting all of our partners for another year of supporting web platform documentation for the benefit of web developers & designers worldwide. We also aim to strengthen our collaborations with existing initiatives like continuing to support Interop and working with the W3C WebDX Community Group to improve the general developer experience for people developing for the web.