Patrick

What's Open Web Docs?

The OWD logo

tl;dr: Open Web Docs is awesome. It's one of the biggest contributors to MDN Web Docs. If you use MDN on a regular basis, consider supporting OWD (💵) so they can continue doing the work that makes all of our web dev jobs easier.

If you're a web developer you have most likely heard and used the MDN Web Docs website. Heck, even if you don't call yourself a web dev, but still write some web code every now and then, you've probably used it.

MDN is an invaluable resource for people using HTML, CSS, JavaScript, SVG, or any other aspect of the web such as security, accessibility, performance, virtual or augmented reality on the web, and so on.

Maybe you don't think about it too much, but pause for a second, and realize how many times you've used MDN to look something up today (or any other day on the job). Take a look at your browser history if you need to. Here is mine, notice how small the scrollbar is, the list goes on and on and on:

The Firefox browser history management tool, filtered on developer.mozilla.org, showing a very long list of pages

If this matches your experience, then take a minute to read this article. It's important to understand how the things we rely on so much actually exist.

Quick history recap

Let's not spend too much time on this, but just for context: MDN was started by Mozilla around 2005. It was then called the Mozilla Developer Network, and it was a wiki used to centralize the documentation for the various Mozilla projects, as well as for the web platform itself (check out this snapshot of MDN in late 2005).

Over time, more and more of the web platform APIs and features got documented on MDN, and it started becoming the de-facto documentation for many web developers. So much that in the late 2010s, other big tech companies, who had their own documentation websites, started redirecting their users to MDN instead and contributing to it. Microsoft, in particular, used to have a lot of web platform documentation over on MSDN, which no longer exists (or rather is now called Microsoft Learn).

The idea was simple: MDN is where people go for web platform documentation, let's focus our collective efforts there instead of duplicating the content and making it harder for people to find what they need.

This led to the creation of the MDN Product Advisory Board in 2018, a group of representative from various member organizations who contribute to MDN, and who meet on a regular basis to discuss the future of the project and provide guidance to ensure MDN continues providing unbiased, browser-agnostic, high-quality documentation. The PAB still exists today.

In 2020, Mozilla unfortunately had to go through a pretty big round of layoffs. The MDN team, in particular, was hit pretty hard. At this point, the MDN team was the one responsible not only for maintaining the website infrastructure, but also for writing a lot of the content, and managing the active community of volunteer doc contributors. The layoffs was a big blow to the project.

Today, Mozilla has a small team of writers and engineers who write content and maintain the website's infrastructure.

Enter Open Web Docs

High-quality documentation for the web platform is critically important so, with a bunch of really talented technical writers now out of a job, and so many devs out there who relied on MDN for their day to day jobs, it was clear that something had to be done.

Open Web Docs was created in January 2021 by the people involved in MDN at the time, including the PAB.

OWD is an independent, vendor-neutral, organization that is responsible for ensuring the long-term health of web platform documentation. It spends all of its resources writing new docs, maintaining existing ones, and managing the community of contributors on today's de-facto web platform documentation website: MDN Web Docs.

OWD is composed of a small team of technical writers (4 full-time employees and 1 part-time contractor) who spend their time maintaining the content, which includes writing new docs, updating existing ones, maintaining the browser compatibility data tables (which, by the way, are also used by caniuse.com), doing code reviews for the community, and so on. Take a look at their 2022 impact report from more details.

So how can OWD do this work? The organization needs to pay those 4,5 people for their work. And to do this, because it's a non-profit organization, it relies on donations! It's funded by a mix of corporate sponsors, Google and Microsoft being the two biggest, and a bunch of individual contributors.

And that's where you come in! If you use MDN on a regular basis, and would find it considerably harder to do your job without it, then consider financially supporting OWD. You can become a backer for as little as $5 per month.

It's simple, without money, OWD can't employ technical writers to continue making MDN as great as it is. Sure, OWD isn't the only contributor to MDN. Mozilla has a team of writers too, other companies contribute docs, and there are a lot of volunteers. But if you haven't done so yet, do take a look at the 2022 impact report. This should give you perspective on how much work OWD does, and how negatively impacted MDN would be if OWD didn't exist. On top of this, OWD isn't just a big part of MDN, it's also a vendor-neutral part of it. When Microsoft, Google, Mozilla, or Apple write their own docs on MDN, they always come with their own lens and biases.

It's not just about the MDN website

Sure the MDN website is very important and if you've read this far you probably use it a lot. But OWD's impact goes further than this.

I mentioned it already, but OWD also contributes a lot to the browser compatibility data tables (BCD) which appear at the bottom of almost every MDN page. But this data is also available as a package on NPM, which is used by many other tools, sites, and IDEs which you might also rely on! Here is a few examples:

Other websites also display MDN documentation. After all the mdn/content GitHub repository, where the docs are stored, is public and open-source, and anyone can use the content or even fork it. That's how devdocs.io is able to display CSS reference documentation for example.

In fact, in a future where the MDN website is no longer the de-facto place where people go to learn about the web, that doesn't change a thing for OWD. OWD's mission is to ensure the long-term health of this critical infrastructure that's web platform documentation, wherever people may be consuming it from.

I don't really want to pay, but my company relies on MDN, what can I do?

If your company has made a big bet on the web, it might not be such a bad idea for the company to financially contribute to ensure the web documentation's future is bright. After all, if the documentation of the browser APIs you're using is a bit outdated, or if the tools you rely on start to be incorrect, your teams are going to have a much harder time doing their jobs.

The less reliable the web platform documentation is, the more experts your company will probably need to hire to reverse-engineer browsers and figure out what works and what doesn't. On the other hand, if high-quality and up-to-date documentation is always there when you need it, you can focus on building your own products.

Here are a few ways you can inform your company about OWD and try to convince them to contribute:

You can get in touch with OWD by using the Contact button on the Open Collective page.

And that's it! I hope this post has helped you understand the importance of OWD and why you should consider supporting it. If you have any questions, feel free to reach out to me on Twitter or Mastodon. I'm part of the OWD Governing Committee, and I'll be happy to answer your questions.