Open Web Docs Impact and Transparency Report 2022
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.
- OWD was the single organization with the greatest number of PRs merged to the MDN content repository.
- OWD provided 60% of all Pull Request (PR) reviews to the MDN content repository.
- The OWD team led a number of writing and documentation infrastructure projects, including:
- Creating and extending documentation to meet the needs identified in the Interop 2022 project, including documenting CSS Colors and Cascade layers.
- Completely rewriting the documentation for the Performance APIs.
- Rewriting CSS core principles of inheritance, specificity and the cascade.
- Documenting all ARIA roles and attributes.
- Making MDN more inclusive by ensuring all examples identify document language, have an appropriate character set, and are responsive, every image has alt text, and human names used in code examples better reflect the diversity of those reading MDN.
- Establishing overall themes for prioritized work.
What is MDN and why does it matter?
In 2022, OWD staff primarily worked on improving and extending MDN Web Docs.
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 is the second most cited documentation site on Stack Overflow, after learn.microsoft.com (Source).
- MDN is visited by 17 million developers every month.
- MDN is the only site with comprehensive reference documentation for the web platform APIs.
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:
- the fifth most commits per month (2683)
- the seventh most committers per month (193)
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:
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:
- The OWD project to add meaningful
altattributes to all images on MDN followed a similar model. The
altattribute was added to images in all code examples, and over 500 images were made accessible.
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:
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:
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:.
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.
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.
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:
- update all MDN's code samples to align with this standard.
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.
- more than 200 PRs were merged by more than 20 volunteers
- OWD staff, and volunteers guided by OWD staff, updated most of the 16332 static examples across 6396 MDN pages.
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.
In 2023 we’re aiming to finish this project by updating the guide pages that live next to the Performance API reference pages.
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:
- Worked with MDN staff to develop new cascade layer documentation, and in the process wrote or rewrote all the !important, specificity, and cascade and inheritance documentation; the most visited CSS pages on MDN.
- Revamp MDN CSS color documentation to include new CSS Color spaces and CSS color functions.
- Several Interop 2022 features were previously documented on their own property, API, and data type pages. Our team worked to ensure interop features, like scroll behavior and the new viewport units were not just listed on their individual pages, but included within examples and reference sections in other pages to alert developers to their existence and encourage their adoption.
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:
...now looks like this:
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
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
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:
- Retained key talent, including some of the original architects of MDN, and engaged them on core projects that have
- Grown the impact of web documentation by making it more relevant, contextual, and available for everyday developers
- Reinforced the collective community management and caretaking of web platform documentation - no single company could begin to recreate these resources, or manage them alone
- Supported new contributors, mentoring tomorrow’s top-class tech talent on best practices and content development at web scale
- Spread collective responsibility and investment in common digital infrastructure among multiple vendors, which
- Reduces risk to the project
- Increases visibility and “ownership” behaviors among invested parties
- Strengthens reliability, longevity, and trustworthiness
- Reduces costs
- Improved breadth and quality of the information and data on
- Core reference documentation
- Browser Compatibility
- Hot-topic technologies for next generation application development, security, and privacy-protecting technologies
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:
- Aaron Gustafson
- Alex Rosenkranz
- Anatoly Ostapenko
- Andreas Kling
- Andrew Chou
- Andrew Sutherland
- Andy Piper
- Baldwin Chang
- Ben Galbraith
- Benjamin Altpeter
- Benjamin Piouffle
- Bertram Gao
- Brendan Ardagh
- Bruce garrett
- César Ornelas
- Chris Hayes
- Chris Heilmann
- Chris McGhee
- Clueless Ruler Music
- Damien Clauzel
- Daniel Ehrenberg
- Danny McGee
- Danny W
- Daren Chandisingh
- Dominic Cooney
- Dominic Cooney
- Eric Casthart
- Eric Shepherd
- Ethan Resnick
- Facebook Open Source
- Fund OSS
- Germain Souquet
- Google Open Source
- Gyuri Lajos
- Harry Dent
- Harry Dent
- Hiroyuki Ota
- Igalia SL
- Ilya Diallo
- Ilya f
- Itai Noam
- Jad Joubran
- Jan P
- Jaroslav Kubicek
- Jeff Posnick
- Jens Oliver Meiert
- Jeremie Patonnier
- Joel Marcey
- John Whitlock
- Jonathan Finch
- Jory Burson
- Joseph Kesselring
- Julien G
- Julien Vanélian
- Julius Tarng
- Junya Kono
- Justin Ridgewell
- Kayce Basques
- Keith Kurson
- Kenneth Rohde Christiansen
- Kostas Bariotis
- Kotaro Morooka
- Kyle Pflug
- Laurent le Beau-Martin
- Leo Balter
- Leonardo Kewitz
- Logan Henrie
- Marcus Weiner
- Mark Reeves
- Mark Reeves
- Martijn Arts
- Masataka Yakura
- Matt Lindeboom
- Michael Leggett
- Michael[tm] Smith
- Microsoft Edge
- Milica Mihajlija
- Mitchell Harris
- Moto Ishizawa
- Nazar Mokrynskyi
- neuland - Büro für Informatik
- Open Collective
- Open Collective
- Oskar Oldorf
- Oussama Romdhane
- Owen Valentine
- Patrick Kettner
- Paul Kinlan
- Pelle Wessman
- Pete LePage
- Peter Antonius
- Peter deHaan
- Peter Rushforth
- Pia Mancini
- Rad Web Hosting
- Rick Byers
- Robert Ma
- Romulo Cintra
- Russell Beattie
- Ryan Prior
- Sam Chen
- Samsung Internet
- Scott Hallock
- Scott Kennedy
- Sebastian Zartner
- Sergio Moraes
- Sharat M R
- Shinichi Segawa
- Stephanie Eckles
- Stilyan Mihalev
- Takayuki Shimada
- Thomas Berntsen
- Thomas Steiner
- tim richardson
- Tom Leen
- Tom Leo
- Tomasz Kleszczewski
- Tommy Williams
- Tsubasa Nomura
- Tyler Wilcock
- Type of Web
- Victor Neo
- Vincent Ramdhanie
- Vladimir Ivanenko
- Xidorn Quan
- Yasuhiro Яша Asaka
- Yoichi Fujimoto
- Yu Matsuzawa (ymtszw)
- Yuhei Yasuda
- Yukio Arita
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.