Sovereign Tech Fund invests in Web Security and Privacy docs

2025-09-30T00:00:00Z

We're proud to share that we're commissioned by the Sovereign Tech Fund to work on expanding developer documentation with security and privacy guidance. Over the coming year, Open Web Docs will be working on creating and updating Security and Privacy documentation for web developers on MDN content.

Security and privacy documentation are key parts of Open Web Docs' core values and we believe the maintenance of these docs is critical digital infrastructure that benefits everyone.

In 2023, we handed in a position paper at the Secure the Web Forward workshop where we presented initial research showing the need for better Security documentation.

In 2024, we joined the newly created W3C Security Web Application Guidelines Community Group (SWAG CG) and since had fruitful conversations on a weekly basis, as well as at W3C TPAC 2024.

In early 2025, we presented a content outline and project pitch to the Sovereign Tech Agency and we're now proud to share that we've been awarded an investment from the Sovereign Tech Fund to work on this topic over the coming year.

The commissioned work contains the following high-level goals:

Defending against attacks

We will be developing a series of guides about common attacks on websites, explaining for each attack: how it works, the impact, and how to defend against it.

We've already started work on this objective in September and you can now find new articles on the most common attacks on MDN Web Docs: https://developer.mozilla.org/docs/Web/Security/Attacks

Threat Modelling for Web Developers

We will be developing a guide that provides recommendations for the specific threats that a website might face based on the features a site implements (such as authentication of users or rendering of user-submitted content).

W3C SWAG CG and Web Security Guidelines

We will continue to be active in the SWAG CG on a weekly basis and at TPAC 2025. We will also continue leading the CG's security guidelines community discussions and determine the most appropriate canonical home for the W3C SWAG Web Security Guidelines document.

Authentication on the Web

Authentication is a large topic with many new options and evolving web standards, such as WebAuthn and passkeys. We will develop a series of guides for web developers to implement authentication techniques, such as passwords, one-time passwords, federated identity, and web authentication.

Security Practices

We will develop a series of guides on security practices, including session management, handling third-party software, user input validation, and operational security.

Privacy Documentation

We're planning to improve MDN's documentation on privacy, by increasing documentation beyond browser-specific features. This work will include:

Research and document privacy technologies that are available to web developers but currently not well known or understood by practitioners.
Work with experts to research, develop and validate a content outline.
Perform initial analysis of the proposed documentation scope, including research into the privacy needs of the developer community and a review of existing documentation.
Validate the resulting scope with privacy experts.
Develop concrete practical guidance to help web developers protect their users.

User interviews and survey

To make sure the guidance and documentation we're creating is useful, we need to understand our audience as best as possible. To achieve this, we plan to:

Develop and run a survey aimed at learning about web developers' security awareness (following up on the 2023 survey from the Secure the Web Forward workshop).
Conduct user interviews to get qualitative feedback on the helpfulness of security and privacy documentation written in this effort.
Analyze survey results and user interviews and create a report.

Thank you!

We're looking forward to sharing our progress on all of these objectives over the coming months. Many thanks to the Sovereign Tech Agency for investing in Open Web Docs!

Launching the W3C Docs Community Group

2025-04-22T00:00:00Z

We're launching a new W3C Community Group, the Documentation CG (Docs CG). This group is an open community with the mission to ensure web developers and designers worldwide have the best information available so they can build things on the web platform.

The Docs CG is open to everyone. If you would like to join, please visit the Docs CG homepage. To follow the group's activities, subscribe to the Docs CG repository on GitHub, where meeting minutes will be posted and asynchronous discussions will take place.

The goal of the group is to provide an open forum for technical writers, documentation practitioners, specification authors, subject matter experts, and web developers to collaborate. While we at Open Web Docs have a lot of experience with MDN Web Docs, we also want to explicitly invite other web platform documentation authors and publishing sites to join and share best practices and create a common understanding of how best to document web platform technologies.

We believe that technical writing is essential for web platform technologies to be adopted and understood globally. We further believe it is necessary to have more conversations between:

Specification authors: the designers of web technologies,
Browser implementers: the implementers of the specifications,
Technical writers: the educators who document the specifications, and
Web developers and designers: the creators who build and design, relying on high-quality implementation and documentation of the specifications.

By offering an active community that brings all of these perspectives together, the Docs CG aspires to facilitate excellent documentation of every web platform feature for every creator designing and building on the web platform.

By existing within the W3C Community Groups program, the Docs CG will greatly benefit from being part of a wider community which will allow us to coordinate efforts in collaboration with other (horizontal) W3C groups, such as WebDX, Security, Privacy, Accessibility, Internationalization, Sustainability, and others.

The W3C Docs CG will be chaired by Lola Odelola (lolaslab.co) and Florian Scholz (Open Web Docs). We'd love to welcome you to the W3C Community Slack (invite) in the #docs-cg channel and to our upcoming Docs CG calls.

To learn more, see the Docs CG charter and the Docs CG GitHub repository.

Bloomberg Joins Open Web Docs

2025-03-18T00:00:00Z

Open Web Docs is excited to welcome Bloomberg as a Gold level sponsor joining the OWD Governing and Steering Committees along with our current Governing members Microsoft Edge, Google and Igalia.

Bloomberg Engineering has a track record of backing open standards and open source, and Open Web Docs is proud to join the list of technology community organizations that Bloomberg invests in. Learn more about Bloomberg’s commitment to Open Web Docs in their Tech At Bloomberg blog post, shared below.

Bloomberg Backs Open Web Docs to Support High-Quality Web Platform Documentation for All

High-quality documentation is essential for innovation and to facilitate the growth of web platform technologies. Open Web Docs (OWD) plays a vital role in providing that documentation, especially through MDN Web Docs, a comprehensive resource covering CSS, HTML, JavaScript, Web APIs, and other web technologies. Our engineers use MDN extensively while performing front-end development for the Bloomberg Terminal – software for finance professionals that uses the Chromium web browser and JavaScript to render its user interface – and Bloomberg.com, among other products used across the financial industry around the world.

Bloomberg is proud to announce that it is now a Gold Sponsor of Open Web Docs. As part of this commitment, Alyssa Wright, a member of Bloomberg’s Open Source Program Office (OSPO) in the company’s Office of the CTO and Board Member of Open Source Collective, will also join the OWD Governing and Steering Committees. Bloomberg’s support will help ensure MDN remains a free resource for developers, suggest documentation priorities, and propose strategic partnerships.

“From my unique perspective as someone who was there at the start of Open Web Docs’ journey at Open Source Collective, I’ve always believed that excellent documentation is the fuel for open source innovation,” says Wright. “By supporting OWD, Bloomberg is investing in the long-term sustainability of the open web. We’re ensuring that developers have the tools they need to build, create, and maintain a healthy and accessible web for everyone.”

Software engineer Daniel Ehrenberg from Bloomberg’s JavaScript Infrastructure & Terminal Experience team, a contributor to TC39 who also serves as the President of Ecma International, adds, “Sponsoring Open Web Docs is a natural part of Bloomberg’s commitment to the web platform. Maintaining the highest quality documentation requires paid, specialized technical writers, who OWD supports. This sponsorship will help ensure that MDN’s content remains comprehensive, updated, and freely available to all. MDN is a vital daily resource for Bloomberg engineers as they develop our products.”

Web technologies are constantly evolving and growing, and documentation needs to reflect that. Open Web Docs relies on donations to employ writers who update existing documentation, write new documentation, and improve documentation infrastructure in collaboration with other organizations. Bloomberg’s support will help fund OWD’s technical writing staff and the ongoing development of crucial documentation.

“Open Web Docs’ goal is to ensure developers and designers have the best information available for free so they can make decisions while building on the web platform. Sustainable funding is essential to our mission,” says Florian Scholz, Open Web Docs Co-Founder and Director. He continues, “Bloomberg has been a long-time champion of open web standards, and we’re thrilled to have them support our mission.” Read more about Bloomberg’s open source-first mission, the company’s commitments to supporting web standards, and ongoing contributions to CSS and JavaScript here. Learn more about Open Web Docs and its charter here.

As an Open Web Docs member organization you support core web platform documentation and engineering which we consider critical digital infrastructure. Reach out to florian@openwebdocs.org for more information and join us!

Self-experimentation with CSP

2024-11-07T00:00:00Z

Last week we landed a big update to the MDN guide page about Content Security Policy (CSP), a web security feature that has a reputation for being complicated and difficult to deploy.

It started with a discussion in the Security Web Applications Community Group about how we can help CSP gain more adoption among web developers. Florian asked whether our site, https://openwebdocs.org, has a CSP, and embarrassingly, it didn't. We thought perhaps that by trying to add one, we might get some insight into the difficulties web developers face when trying to deploy their own.

Strict CSP

Netlify generously host openwebdocs.org under their Open Source Plan. So I went there, and found a very interesting post: How I learned to stop worrying and love the Content Security Policy, which describes how Netlify supports a style of CSP which uses a nonce (number used once) to determine whether scripts are allowed to execute, rather than a CSP that lists acceptable hosts. The general idea is that every time a document is served, the server generates a random value, and embeds this value both in the CSP header and in the nonce attribute of any <script> tags. The browser checks that the value in the header matches the attribute value, and refuses to execute the script unless they match. Because an attacker can't predict the nonce, they can't add a valid nonce attribute into any script tags they manage to inject.

A big attraction of this approach is that it's much easier to implement than listing acceptable hosts: the Netlify article notes that just adding Google Analytics to your site requires you to add 187 domains to the list.

Next, I found that although both web.dev and OWASP recommend this style, which they call a strict CSP, MDN doesn't even mention it. So we filed an issue and started updating the docs.

Does OWD need a CSP?

While we were discussing how to add a CSP to the OWD website, Estelle asked a really good question: does our site need a CSP? In our pull request to update the CSP guide, Hamish had a similar comment: how, specifically, does a CSP protect websites from XSS?

Our current documentation tended to go like this:

XSS is bad

CSP protects you from XSS

So you should have a CSP

We need to go deeper than this. We ought to explain when and how XSS can cause specific problems for sites, and exactly where a CSP can help: where the features of a CSP meet up with the prongs of an XSS attack. We ought to explain how the threats and corresponding protections might be different for different sites. For example:

a site where the server dynamically constructs responses from templates, based on the contents of a database
a single-page app that uses client-side rendering to update the page content
a more or less static site where the server always serves the same content, and the page contains little to no JavaScript.

Our CSP guide update made some steps towards this, but there's more work to do here: in particular we need better documentation of XSS, to cover the different ways an XSS attack can be made and the different tools that can be used to counter it: not only CSP, but tools like trusted types and output encoding.

Auto-CSP

The Netlify feature also connects with an idea that was mentioned in the TPAC session on security docs and which recently landed in Angular: tool support to deploy a CSP automatically based on a configuration setting. We'd like to include this in our CSP documentation and again, we'd like to talk about not just its existence but the specific web app architectures for which it is appropriate.

For example: in a strict CSP, the server typically uses a template to insert nonces into the script tags it intends to include in the document it serves:

<script nonce="{{nonce}}">
  // ...
</script>

The server's explicit intention is important here: it means that even if an attacker tricks the server into inadvertently including a malicious script (for example, in a reflected XSS attack), then the injected script won't contain the nonce, and it won't execute.

By definition, though, auto-CSP doesn't understand the server's intention. Netlify's dynamic CSP runs in the CDN, and automatically injects the nonce into every <script> tag it finds in the document that the server provided. If this contains scripts that the server inadvertently included, they will be given the nonce, and will be allowed to execute.

What Netlify's CSP does is protect against client-side script injection, where the front-end code inadvertently inserts a malicious script by calling an unsafe DOM API like document.write(). So this kind of CSP is appropriate for a web app that uses client-side rendering.

So... does OWD have a CSP yet?

Not yet! We're technical writers, so as soon as we learn something new, we have to make sure all the docs are updated first. But our practical investigations have already generated improvements to MDN's security documentation, and as we've seen in this post, there's much more to come.

Security documentation at TPAC 2024

2024-10-22T00:00:00Z

In September, Open Web Docs attended TPAC, the main annual meeting for the W3C. It's the first time we've been together for almost 2 years, and it was great to reconnect with each other and with many of our collaborators. We proposed and chaired a breakout session about the activities of the Security Web Application Guidelines Community Group (SWAG CG), and in this post we'd like to summarise some of the discussions that came out of this.

The SWAG CG was formed by Dan Appelquist in June 2024 and has been meeting weekly since then. Its mission is:

To increase the overall security of web application development, thereby making the web a more secure platform for web users. It will accomplish this by writing security best practices for web developers and providing a platform for stakeholder collaboration.

Open Web Docs participates in this group because we think better documentation will improve the state of web security, and we think the SWAG CG can reveal gaps in web security documentation and provide technical support for us as we work to fill them.

At TPAC we presented four topics in security documentation that have come up through the work of the SWAG CG:

Security 101: a page, or a series of pages, on MDN, listing fundamental things a developer can do, that have a big impact on the security of their site. This is partly addressed by the work Chris Mills has done on Practical security implementation guides, but there may be further updates needed.
Security considerations for Web APIs: some web platform features — fetch(), for example — have special implications for web security. Features like this should have a "Security considerations" section in their reference pages summarizing these implications, so they're more apparent to developers using the feature.
Frameworks and libraries: security documentation should help developers make good choices about which third-party software to use, either by recommending specific libraries or by writing guidelines that developers can use to make their own choices.
Content security policy (CSP) adoption: can more consistent and approachable documentation help more developers implement an effective content security policy for their sites? While OWASP recommends a strict CSP which uses nonces and hashes rather than an allowlist, MDN's documentation does not mention strict CSP. We should aim for consistency here so we can give a clear message to developers.

The conversation that followed took in a number of interesting ideas in connection with these topics, and we've highlighted a few of them below:

It would be easier for developers to deploy a CSP if it were provided out of the box by frameworks and libraries.
We should consider not just documentation but the full set of support that developers can use to implement secure websites, including developer tools and testing. There may be opportunities for integrating documentation into workflows. For example, if there is tooling to help test whether a website will break when its CSP is deployed, we could integrate errors with documentation, so developers can understand and fix the issues (note that this is what the Mozilla observatory is already doing).
We should relate security documentation to the developer journey, mapping guidance to the lifecycle of a project. For example, when a developer chooses their dependencies, they should consider how this choice will impact the CSP they will want to enforce.
How should we maintain security documentation as guidance changes? Sometimes a security recommendation becomes less important as browsers deploy more secure defaults (for example, with respect to Referrer-Policy). This is like Baseline: once a feature has good browser support, knowing the exact support situation is less important. One way to help with this is to document attacks separately from specific mitigations: while guidance about mitigations changes relatively frequently, the threats faced by web developers tend to stay the same over time.

The next steps for Open Web Docs are to revise MDN's CSP guidance, to write a set of pages documenting common attacks, and to integrate feedback on the "Security 101" material on MDN.

As writers, especially in a relatively specialized area like security, it's critically important to have this kind of engagement with domain experts, so we're very grateful to the participants in the SWAG CG and in the TPAC session for their time and expertise. If you're interested in how we can give better security guidance to web developers, we'd encourage you to participate in the SWAG CG, as well!

CSS containment

2024-04-10T00:00:00Z

One of Open Web Docs's 2024 goals is to document features supported by the three major browser engines, including ensuring all Interop features are fully documented.

We are starting by documenting all the features of Interop 2021-22 and 2023. Later this year, we will focus on the Interop 2024 features that will, at that point, be newly supported.

CSS containment project

The first sub-project completed was CSS containment. CSS containment is part of both Interop 2022 and Interop 2023, and is still being worked on as part of Interop 2024.

Containment improves rendering performance by isolating sections of content for delayed layout and rendering. Container queries, also defined in the CSS containment specification, enable targeting styles based on a container's size or style features.

We created a new CSS containment module landing page and guides. The module landing page includes a reference with links to all the properties, at-rules and descriptors, CSS functions, events, interfaces defined in the CSS containment specification, and guides. All these references were reviewed and updated as necessary.

The larger component of this project included updating the existing containment guides and creating new ones.

CSS containment guides

There are now three CSS containment guides on MDN:

CSS container queries

We updated this introductory @container queries guide, which discusses size queries, naming queries, and container query length units, which are well supported. We left in the fallbacks for non-supporting browsers for now, and look forward to removing it soon when it's fully supported!
Using CSS containment

We fully updated this guide which describes the basic aims of CSS containment and how to leverage contain and content-visibility properties for a better user experience. The guide explains size, layout, style, and paint containment.

We also moved this guide to be under the associated CSS module landing page, to improve maintainability and match our current structure.

The contain property is supported in all browsers. The two other main features defined in the containment specification are content-visibility and @container. These features have more limited support. But, as per the goals of Interop, support is improving, and documentation for these up and coming features is now available! content-visibility improves the initial page load speed by enabling browsers to omit sections of layout and rendering until the content becomes needed. And @container enables applying styles to an element based on the size or style feature of a containment context.
Using container size and style queries

This represented the bulk of the project. The new guide focuses on writing container size and style queries with @container, including style queries for custom properties, query syntax and names, and nesting container queries.

This new guide covers all the basics of currently supported container queries including a deep dive into container size queries and the size query descriptors, naming containers to limit their scope, and using the style() functional notation within the @container at rule's <container-condition> to create style queries with custom properties.

The guide also touches on container style feature queries, as we await browser support for this exciting feature.

Open Web Docs

Thanks to the support of our sponsors, we, the OWD technical writers, are able to review and update existing content and dedicate the time needed to write in-depth articles when documentation is found to be lacking. We found a gap in the documentation of container style queries, and had the support to fill it!

If you use MDN and find these resources helpful, please consider sponsoring OWD on GitHub or becoming an Open Web Docs sponsor on Open Collective. Contributions are what make OWD and our documentation efforts possible.

Igalia Joins Open Web Docs Governing Committee

2024-03-18T00:00:00Z

Open Web Docs is excited to welcome Igalia to our Governing Committee, joining Google and Microsoft Edge. The Governing Committee administers OWD’s financial sponsorships, made via Open Collective, and explores strategic partnerships and needs for web documentation projects.

The Governing Committee is composed of organizations sponsoring at the Platinum level, elected representatives from the Gold membership level, individual advisory members, and OWD’s Director.

Igalia is a software consultancy focused on open-source software. Igalia is known for its contributions and commitments to both open-source and open standards. They are a key contributor to every browser engine and lead the development of many Web feature implementations that Open Web Docs supports with documentation.

“Igalia has been a staunch supporter of Open Web Docs since its inception, and we‘re honored to become part of the Governing Committee. On a more personal level, everything about OWD’s mission resonates with me, so I’m excited by this opportunity to participate more actively in the work.”
– Eric Meyer, Developer Advocate at Igalia

“Igalia has been a long-time partner to OWD and a big supporter of open web documentation. Igalia has been a key member in our Steering Committee since OWD’s inception in 2021. I’m thrilled to have Igalia on our Governing Committee going forward.”
– Florian Scholz, Director of Open Web Docs

With a $20k yearly donation, Igalia is an OWD Gold Sponsor, helping us reach our yearly goal of fully funding four full-time technical writers to work on open web documentation.

Introducing our Director of Open Web Docs - Florian Scholz!

2024-03-06T00:00:00Z

The Open Web Docs Governing Committee is thrilled to announce that Florian Scholz has been appointed as the new Director of Open Web Docs (OWD), stepping into a pivotal role that is crucial for the advancement and stewardship of the project. This appointment marks a significant milestone in the OWD journey, reflecting our continuous commitment to enhancing web platform documentation through collaborative and open efforts.

Florian previously served as OWD’s Content Lead. As Director, Florian will be at the forefront of both internal and external matters concerning the OWD project. Internally, his responsibilities will encompass chairing the Steering Committee, leading our dedicated staff writers, and collaborating with stakeholders to establish and execute projects aligned with our quarterly roadmap. His role is integral to ensuring that the vision and goals of the OWD project are met with enthusiasm, precision, and excellence.

Externally, Florian's leadership will extend the visibility and awareness of the OWD project. He will engage directly with our partners to brainstorm new project ideas, explore funding opportunities, and initiate community development activities. His efforts will not only strengthen our current partnerships but also forge new ones, broadening the horizon for OWD's impact on web documentation.

Florian’s expertise and dedication are invaluable for the community of contributors, and set a high bar for technical writing and documentation engineering within the OWD ecosystem. With a rich background in technical writing and a passion for open web standards, Florian is well-equipped to lead the OWD project towards achieving its goals. His leadership, mentorship, and expertise will help foster an environment where collaboration and innovation in web platform documentation thrive.

Please join us in congratulating Florian on his new role.

Using Web IDL for better web docs

2024-02-08T00:00:00Z

In this post we'll look at an investigation into the possibility of using data extracted from the W3C specifications to help make MDN more consistent, reliable, and maintainable. We're not yet sure where this idea will end up, but we hope the post gives an insight into how we evaluate large-scale changes to such an extensive documentation set. As always, the devil is in the details!

Web IDL and the MDN Web/API documentation

The biggest single piece of MDN, accounting for about half the total number of pages, is Web/API, which consists of reference documentation for the JavaScript APIs that are implemented in browsers. These features are defined, of course, in specifications, and the specifications use a language called Web IDL to describe precisely what each API looks like. For example, here's the Web IDL for the PushSubscription interface:

[Exposed=(Window,Worker), SecureContext]
interface PushSubscription {
  readonly attribute USVString endpoint;
  readonly attribute EpochTimeStamp? expirationTime;
  [SameObject] readonly attribute PushSubscriptionOptions options;
  ArrayBuffer? getKey(PushEncryptionKeyName name);
  Promise<boolean> unsubscribe();

  PushSubscriptionJSON toJSON();
};

There's a lot of information in the IDL that maps to the reference documentation on MDN, including, for example:

the name of methods and properties belonging to an interface
the names and types of parameters
whether parameters are optional
whether properties are read-only

At the moment, this mapping is maintained entirely manually: MDN authors have to check the IDL when writing a page, and reviewers have to manually check PRs against it. Moreover, we have no systematic way to update MDN when the specifications are changed or extended.

At Open Web Docs, we're interested in using and developing tools to reduce the maintenance cost of documentation while improving its consistency and reliability. So we recently spent a bit of time looking into one feature of the Web IDL, the SecureContext extended attribute, to see if we could use it in MDN.

Secure contexts

Many web platform features are only available in secure contexts. This usually means that the script's document was served over HTTPS (but browsers also treat URLs like localhost as secure contexts, to make local testing more convenient).

When a feature is only available in secure contexts, MDN authors indicate this using macros in the Markdown source: the secureContext_header macro adds a banner across the rendered page. So if an author includes a line like {{secureContext_header}}, then the rendered page will contain a box like this:

But this is maintained entirely manually, for all the thousands of web platform features that require a secure context.

Meanwhile, the specifications record "secure context required" using a Web IDL attribute SecureContext:

partial interface mixin WindowOrWorkerGlobalScope {
  [SecureContext, SameObject] readonly attribute CacheStorage caches;
};

The @webref/idl package, maintained by the W3C, makes the Web IDL definitions machine-readable. What if, with the help of this package, we could use the Web IDL definitions to add the "secure context required" box to MDN pages automatically?

The analysis

We wanted to see if we would be able to map from features identified in the Web IDL to MDN pages, and how often we would encounter discrepancies between the IDL's SecureContext attribute and the presence or absence of the macro in the corresponding MDN pages.

We wrote a tool that sorted features defined in the Web IDL - interfaces, properties, methods, or events - into two groups: those that require a secure context and those that do not. Then we made two groups of Web/API pages on MDN: those that contained the secureContext_header macro, and those that did not. We then made three lists of anomalies:

Items whose MDN pages contained the secureContext_header macro, but which were not marked SecureContext in the Web IDL.
Items marked as SecureContext in the Web IDL, but whose corresponding MDN pages did not contain the secureContext_header macro.
Items whose MDN pages contained the secureContext_header macro, but which did not have a corresponding entry in the Web IDL.

For the first two of these, using Web IDL as the source of truth would change the MDN pages. We would like to know: would this change be for the better, or for the worse?

For the third, we would not be able to update these pages at all from Web IDL. What would we like to happen in these cases?

Secure context in MDN, not secure context in Web IDL

This lists all features that are marked secure context in MDN, and not marked secure context in Web IDL (but do exist in Web IDL). If we just use Web IDL as the source of truth, then these MDN pages would no longer mark the features as secure context.

We found 61 items in this category. Most of these are cases where a feature effectively requires a secure context, although it is not marked as such in the spec. For example:

The getCurrentPosition() method of Geolocation is not marked as requiring a secure context, but the implementation of the method requires constructing a GeolocationPosition object, and that does require a secure context. So MDN marks getCurrentPosition() as requiring secure context.
The Notification interface is not marked secure context, but it is defined as a powerful feature requiring permission, and getting permission itself requires a secure context. So, again, MDN marks Notification as requiring secure context.

In cases like this, it seems like the docs would be worse if we used Web IDL as the source of truth.

Secure context in Web IDL, not secure context in MDN

This lists the other direction: features that exist in both MDN and Web IDL, that are listed as secure context in Web IDL but not in MDN. If we just use Web IDL as the source of truth, then these MDN pages would start to mark the features as secure context.

We found 668 items in this category! We haven't looked at all of them, but in all the cases we have looked at, this is an error in MDN. A common source of this issue is when the interface is marked as requiring a secure context, which means all its members require secure context. Often in cases like this MDN will only mark the interface page as requiring secure context, and not the method or property pages.

So for this direction, using Web IDL as the source of truth would fix hundreds of MDN pages.

Secure context in MDN, nonexistent in Web IDL

In this category we have features that are documented on MDN, but that don't have corresponding items in Web IDL at all. If we use Web IDL as the source of truth, what can we say about features that don't exist in Web IDL?

There are 38 pages in this category. They fall into two types: nonstandard features, and places where MDN does not directly represent IDL structures.

Nonstandard features

In our study, almost all of these are features that used to be standard but were then deprecated and removed from the specification: for example, PaymentAddress. Perhaps it's not so important to display secure context information for these.

However, nonstandard features are generally a problem for any broader attempt to use Web IDL as a data source. It's been suggested that we could extract the browser-specific IDL and make a nonstandard companion to the webref/idl package.

Mapping discrepancies between Web IDL and MDN

MDN does not always directly document Web IDL structures, and this is generally a deliberate choice based on the belief that different structures serve MDN's audience better.

One example of this is mixin interfaces. In Web IDL, specification authors can define members - attributes and methods - on a mixin interface, which can then be added to one or more interfaces. For example, in the Fetch standard, the Body mixin is included by both the Request and Response interfaces.

Mixin interfaces aren't visible to web developers as a separate thing, though: they are a convenience for specification authors. As the specification says:

Interface mixins, much like partial interfaces, are intended for use as a specification editorial aide, allowing a coherent set of functionalities to be grouped together, and included in multiple interfaces, possibly across documents. They are not meant to be exposed through language bindings.

So MDN doesn't model mixins, preferring to duplicate the mixed-in members in all the concrete interfaces that include them:

We think this is a good choice for MDN, but it means we have to transform Web IDL before we can map it to MDN pages.

When MDN is consistent about divergences like this, and the rules are clear, then we can perform these transformations and successfully map from Web IDL to MDN. But sometimes MDN is not consistent. For example, Web IDL includes an iterable declaration that can be applied to any interface. This effectively means the interface will have the members required by an iterable, such as entries(), forEach(), keys(), and values().

When an interface is declared iterable, should MDN have separate pages for each of these methods, as it does for Array? Or should it just indicate that the interface is iterable, and link to the Array pages for the details?

In practice, different authors documenting different interfaces have made different choices here. And without consistency, we can't reliably map from Web IDL to MDN pages.

We've outlined a project to take care of these discrepancies, but it will take a while to resolve: https://github.com/openwebdocs/project/issues/159.

What's next?

This story doesn't have a neat ending yet. There's definitely scope to use Web IDL in MDN pages. Already one of the most prolific volunteer contributors to MDN, Onkar Ruikar, has used this analysis to add the secure context macro to all the MDN pages matching our second list of discrepancies, where the Web IDL marked the corresponding feature as needing a secure context.

We're pretty sure there are more ways we can use Web IDL, both for secure context and for other aspects of the docs. As this analysis shows, there are challenges too, some of which we know how to resolve and some we don't, yet.

We hope this post has given some insight into how we assess and plan systemic changes to the docs. And we hope that as we work through the issues we'll be able to make more use of Web IDL in MDN, making the docs more consistent, reliable, and maintainable.

Thanks to all our 2023 and 2024 sponsors

2023-12-22T00:00:00Z

In 2024 Open Web Docs will enter its fourth year of operation, and our mission remains the same: to create and maintain the best possible web platform documentation, and make it available to everybody. We’re entirely funded by sponsors, and we’d like to thank everyone who has sponsored Open Web Docs this year.

Our two Platinum and founding sponsors, Google and Microsoft, have again sponsored us for 2024. Our Gold sponsor Igalia and our Silver sponsor Canva are also continuing their sponsorship. We’re grateful to all these organizations for their consistent support and their belief in the importance of our work.

This year we’ve also been sponsored by the Sovereign Tech Fund, to continue our development of tools for the browser compatibility data project, particularly the Open Web Docs mdn-bcd-collector project. The STF will also sponsor us again in 2024, and we’re really happy to see governments lending support to sustaining open source projects.

We’d also like to thank all the individuals who donated to us: we greatly appreciate your support and belief in our mission. All our donors are listed on our Open Collective page.

If you or your organization is interested in becoming an OWD sponsor, we would love to hear from you. Please reach out to florian@openwebdocs.org.

We are a very low-overhead organization that converts all of this sponsorship into web documentation. Here’s a quick summary of the major projects we completed in 2023 thanks to you all:

Additionally, we’ve continued the day-to-day maintenance of the mdn/content and the mdn/browser-compat-data repositories, fixing issues and reviewing PRs. Thanks to the awesome people who volunteer their time to help improve MDN: working with you is one of the highlights of this project.

Thank you, also, to the Mozilla MDN team for being great partners as we collaborate on maintaining MDN.

We have lots of plans for 2024, which we’ll share with you in the new year!

Sovereign Tech Fund invests in Open Web Docs

2023-10-19T00:00:00Z

We’re proud to share that we’re among the selected projects in the Sovereign Tech Fund’s Contribute Back Challenges.

The Sovereign Tech Fund (STF) supports the development, improvement, and maintenance of open digital infrastructure in the public interest. Their goal is to sustainably strengthen the open-source ecosystem with a focus on security, resilience, technological diversity, and the people behind the code. STF is funded by the German Federal Ministry for Economic Affairs and Climate Action (BMWK) and hosted at and supported by the German Federal Agency for Disruptive Innovation GmbH (SPRIND).

STF’s investment in OWD will support two MDN browser-compat-data (BCD) projects that address how BCD is updated, maintained, and accessed:

Project 1: Implement a process for updating BCD whenever a new browser release is available
Project 2: Group web platform features

These BCD projects will better enable web developers to create websites that are compatible with many different web browsers.

OWD receives funding from multiple organizations and individuals to work on open web documentation and the tools that support this documentation. Part of this has been the continued manual updating of BCD. With the support of STF, we have the opportunity to create tools that streamline BCD maintenance, while improving real-time accuracy. We will be working on these two projects for the rest of the year, and of course, anyone is welcome to contribute and participate. As always, all work will be done in the open.

We're very happy that Open Web Docs' application to STF was successful and that it will allow OWD to make browser compatibility data even more up to date and easier to use.
We've always believed that high-quality and up to date web platform documentation is a critical piece of our digital infrastructure. OWD getting the fund is an important validation of the work they do, and will help them continue running a successful open source project.
– Patrick Brosset, Microsoft Edge, OWD Governing Committee Member

Developers frequently tell us that understanding what is available on the web and across browsers is critical for them to be able to build sites that serve their users well. This funding will directly help developers understand what they can use and rely on on the web and bring forward a healthier and more interoperable web.
– Paul Kinlan, Google Chrome

Thank you STF for selecting us!

Docs to Secure the Web Forward

2023-10-05T00:00:00Z

Open Web Docs attended the W3C workshop Secure the Web Forward. The workshop was held virtually on September 26-28, 2023 with the goal to drive developer awareness and adoption of web security standards & practices.

We handed in a position paper called Documentation for web security education and presented our paper as part of the "Developer awareness" track on the last day of the workshop.

In the paper, we take a look at the MDN short survey results on web security.

The responses to the survey suggest a clear need for better education, tools, and best practices to assist developers in detecting and preventing security vulnerabilities in their development workflows. On average, 60% of developers rated the security aspects as somewhat challenging or very challenging, while only 17% of developers rated them as easy or very easy.

With this need in mind, we took a look at the current state of the MDN security documentation area, proposed a better structure, and started conversations how to create better documentation for web security.

The talk was recorded:

Many thanks to the program committee and in particular to Dan Appelquist (Snyk) and François Daoust (W3C) for inviting us and for all the work on organizing this workshop!

Some takeaways from the discussion that followed the presentation of our paper:

Agreement that documentation plays a major role in the adoption of best practices and in understanding threats and defense mechanisms.
Lots of support for a standard "Security considerations" section in reference docs, like MDN has for accessibility.
There is some gatekeeping going on: We should aim to empower more people and make security more accessible to everyone and not act like security is some else's problem. (or only the browser's problem, or only a problem on the server side).
Related: No need to be a "Security expert" to care and work on security. Everyone should be responsible and even doing basic checks is already better than doing nothing at all.
We need to document end user impact: the why, and the potential harm, to help developers (and their managers) understand the value of good security practices.
We will see regulation in this space, for example the Cyber Resilience Act, but there are no guidelines or best practices. Maybe we need WCAG but for security to help inform regulations.
Can we incorporate security advice inside IDEs and devtools?
Can we have demos of security problems, to make them less abstract?

As a next step, we hope to meet again with interested folks to:

Workshop a content outline for structured documentation on web security including the four quadrants of documentation (tutorials, how-tos, guides, reference).
Get more insights into developer needs and misunderstandings in the web security field (maybe through additional surveys or user interviews).
Create guidelines for a "Security considerations" section on reference pages.

We hope to use all of these discussions, the research and the work on a content outline to formulate an Open Web Docs project on web security documentation which we can work on in 2024.

Please reach out to Florian or to Will to be included in planning.

OWD at TPAC Sevilla

2023-09-21T00:00:00Z

Last week I traveled to Seville, Spain to attend the W3C TPAC 2023 conference.

Every year, the W3C TPAC conference invites W3C members and boards, W3C Working and Interest Groups, as well as Invited Experts and others to meet and discuss work on web standards and web technologies. This time, it was a hybrid event - participation was possible both in-person and remotely.

It was my first in-person TPAC event. I enjoyed meeting a lot of folks that I had only interacted with online so far. It was a great feeling when people recognized me or Open Web Docs and had nice things to say.

I received kudos for Open Web Docs' setup as a non-profit Open Collective. I was also told that folks enjoy reading about the projects we do on MDN Web Docs. Some TPAC attendees I spoke with even watch our GitHub project repository to immediately hear all about our new projects (cheers, Thomas Steiner!).

Attending an in-person event these days is really about the people. So, let me give a shout-out to "my" people at TPAC: I connected with a few OWD governing board members, including Rachel Andrew (Google), Daniel Appelquist (Snyk), Patrick Brosset (Microsoft), Dominique Hazael-Massieux (W3C), and Robert Nyman (Google). I also met members of OWD's steering committee, including Ruth John (Mozilla), Brian Kardell (Igalia), Lola Odelola (Bocoup), Brian Smith (Mozilla), and Michael[tm] Smith (W3C).

Since our founding, we have only had a single OWD meetup (in London, earlier this year). It was so lovely to reconnect and talk about web platform documentation once again.

Technical writing breakout session

For me, the most interesting day was Wednesday. Wednesday was an unconference-style day of breakout sessions. In collaboration with Rachel and Patrick, I chaired a breakout session, "Getting your feature adopted: learn to work with technical writers." In this session, we invited the participants to discuss how technical writing and documenting web technologies can be improved. We touched on topics like finding relevant Subject Matter Experts (SMEs) and presented how documentation typically gets written and maintained. Shawn Lawton Henry (W3C), of the Web Accessibility Initiative, joined us. She informed us that they are currently seeking a technical writer for the Understanding WCAG docs. We also discussed the challenges with Webviews that ought to be documented with Sam MacBeth from DuckDuckGo. Read the full minutes of our session.

There were several things I truly enjoyed about chairing and attending TPAC sessions. I really appreciate how scribing was taken seriously. I also appreciated how to be added to the speaker queue, all one has to do is type "q+" in the IRC channels. As an introvert, it can be quite stressful to figure out the right moment to speak up in a room full of (incredibly smart) people. Thanks to this inclusive feature, I q+'ed myself, was acknowledged by the chair, and was able to ask my question or share my perspective. If you are interested in more mechanics of this, I found a blog post on the Bocoup blog: How to scribe at TPAC.

More sessions

I recently joined the WebDX W3C community group and attended breakout sessions related to WebDX:

Interop project, chaired by James Graham (Mozilla).
Beyond Interop, chaired by Kadir Topal (Google).
WebDX research and spec development, chaired by François Daoust (W3C).
Secure the Web Forward, chaired by Daniel Appelquist (Snyk).

Open Web Docs will be collaborating with the WebDX group a lot more going forward. Documentation is a major aspect of Developer Experience! As such, the research and work this community group is doing is very relevant to OWD's mission. As part of the goal of improving developer experience through better documentation, I met with Daniel Beck and Kadir Topal (Google) to discuss the next steps for the OWD project "Grouping web features". Daniel also made a video about web features.

The "Secure the Web Forward" session was also good preparation for the Secure the Web Forward virtual workshop happening September 26-28. We are eager to discuss web security documentation and lessons with security experts. While talking to Arnaud Le Hors (IBM), I realized we should likely start our security docs project by outlining the contents for an "MDN guide to secure your website/web app". I am curious to see how the format will play out, but know this workshop will be invaluable in reaching this project's goals. Expect a blog post about it soon!

Wrap up

And that's it! I really enjoyed the face-to-face conversations, even if it was just briefly near the pool with Bert Bos, Brian Kardell, Ali Spivak, Oliver Dunk, Andreu Botella, and others whom I'm (rudely, sorry!) forgetting right now. Also, a happy birthday shout-out to Diego González. Next year we'll have to celebrate with another great dinner at a different but equally fantastic Tapas restaurant.

I hope to see you all at TPAC 2024! Next year, let's bring the whole OWD team. They currently have some serious FOMO for missing out on this year's event!

Micro benevolences

2023-08-08T00:00:00Z

Many of us are unknowingly responsible for microaggressions in our everyday interactions, including when we write content and create examples for MDN. The Open Web Docs team has been working to reduce the occurrence of microaggressions and up the number of micro-benevolences throughout MDN.

Reducing microaggressions

Microaggressions are demeaning experiences in seemingly normal daily interactions from generally well-intentioned people who are unaware their behavior is non-inclusive and even offensive.

The use of stereotypes is an environmental microaggression. This may be manifested by who is portrayed as a knowledgeable teacher versus who is portrayed as naive and needing to learn. The absence of diversity is also an environmental microaggression. Ensuring representation in curricula and the overall culture of an organization, in general, improves diversity. The absence of diversity, such as including only or mainly cis-hetero-white-men of North American and European descent in relationships with power dynamics, in prose and code are environmental microaggressions.

When people are not represented, they feel invisible. When people from minoritized communities do not see themselves represented in learning or workplace settings, which includes MDN, they can feel isolated, lonely, and excluded. When the only minoritized representations are of learners and students, these microaggressions can negatively impact confidence.

Microaggressions aren't just related to birth-based differences. Language is important for all readers. Describing something as "simple" or "easy", or telling a developer to "just" do something, makes those who don't find something simple or easy, or have never encountered a task, API, or property, feel inadequate or incompetent, and can lead to imposter syndrome. Microaggressions negatively impact everyone's mental and emotional health.

The OWD team has been working to remove potential microaggressions on MDN content. For example, when we encounter words minimizing the complexity of a task, we remove them.

Adding micro-benevolences

A micro-benevolence is a small act of kindness that benefits another person, without expecting reciprocity. Micro benevolences can be as basic as including culturally sensitive names in code examples or putting primary parent and secondary parent on a form instead of defaulting to cis-gendered, patriarchal, heteronormative norms.

In addition to removing potential microaggressions on MDN, the OWD team has been working to include micro-benevolences in code examples and imagery when we update content. As we work thru new content and revise old content to meet new specs and coding standards, we update the text and code examples to reflect the diversity of our readers. By increasing the diversity of cultures, genders, ages, and topics portrayed in code examples, more of our readers will feel seen and included. Another great benefit is that all readers will be exposed to cultures, genders, ages, and topics of interest not their own.

Diversifying code examples

When learning to code, you will often encounter John Doe and Mike Smith in code examples, with the occasional Jane and Kim. The OWD team went thru the content directory and updated such examples to better reflect the diversity of developers. For example, the first names in a table of names was updated to include common first names of different cultures, such as Diego, Shilpa, Caterina, Jayla, Aisha, Kyouko, and Shireen, and non-gendered names, such as Dominique, Jayla, and Gila.

Opportunities for benevolence abound; another table was a list of names and countries was updated to included country-appropriate names, and indigenous names, such as Tlayolotl for Mexico.

With a little effort, and mostly awareness, we hope to make all people feel included and seen.

We also included examples that made people who are often discriminated against and marginalized feel seen. On the web, many code examples are geared toward science fiction and math lovers. While we haven’t removed all references to Star Wars, all male sports teams, planets, or Pythagorean, we’ve included quotes by Maya Angelou, SVGs of mandalas, and a welcome to our trans friends.

We are also encouraging the community to be aware of historical discrimination and exclusion and how history impacts our examples. For example, a community contributor suggested a code example that included the top scorers for the 1954 World Cup. Originally, FIFA allocated only one spot in the World Cup to the three continents of Africa, Asia, and Oceania (one spot in total, not one to each continent). While most people know that FIFA excluded women for most of its history, most don’t know that over half of the world’s male population was also excluded. In this case, we guided the contributor thru the PR review process to use a more inclusive statistic. In so doing, we both improve the inclusion in this single example and made contributors more aware of being mindful when creating examples.

Build a menstrual cycle tracker PWA

2023-08-01T00:00:00Z

Menstruation, also known as a period, is the monthly shedding of the lining of the uterus. Most people assigned female at birth (AFAB) start menstruating as a preteen or during their teen years with periods occurring at regular intervals by the time they reach their twenties.

Menstruation is one of the four parts of the menstrual cycle. The first phase of the menstrual cycle is menstruation. While menstruation usually lasts for three to five days, the length varies between people and between stages of one’s life. The follicular phase is when an egg matures in one of the ovaries. Ovulation is the phase when the egg is released from the ovary. Ovulation usually occurs 14 days before the next menstrual period. The luteal phase occurs after ovulation; the empty follicle in the ovary produces hormones that prepare the uterus for pregnancy. If pregnancy does not occur, the lining of the uterus is shed and the menstrual cycle begins again. Of these, menstruation, due to the shedding of the uterine lining, is the easiest one to track the menstrual cycle.

There are many reasons why people who menstruate want to track their periods. Tracking periods helps predict when ovulation occurs which is important for family planning, whether one is hoping to get or not get pregnant. Knowing when a period is due helps in planning; knowing when to pack period hygiene supplies, when to plan or avoid planning activities, or when to not wear white pants. If one suffers from cycle-related mood swings, cramps, bloating, and fatigue, knowing when these symptoms are likely to occur is important. Tracking menstruation helps identify cycle changes and irregularities, which can indicate a health problem.

Menstrual cycle tracking applications (MCTs) help individuals track their periods. Depending on the MCT, these apps can collect a wide range of personal and sensitive data from flow and symptoms, to sexual activity, to other health information, such as weight, blood pressure, and mood. The main thing they all have in common is they track the first date and end day of each period. The main problem most MCTs have is privacy.

MCTs collect a wide range of personal and sensitive data about users. When using an MCT web application you didn’t write and don’t control, your data is at risk. Personal information, especially sensitive health and reproductive data, can be used to identify users. Privacy risks include:

Data misuse: Once data is shared, you have no control over how it is analyzed or used.
Data collection and sharing: Data may be shared with advertisers, data brokers, and law enforcement.
Data security: Databases run the risk of data breaches.

This is especially concerning in areas that try to regulate or even criminalize reproductive health care, including contraception and abortion. The Florida High School Athletic Association considered a policy to require girls to provide information about their menstrual cycle. Fortunately, this policy was not implemented. Restricting access to abortion, and even access to contraception is not limited to the USA. There is a legitimate concern that MCT data can be used to prevent girls from playing sports, prosecute people who have abortions, and legislate the bodies and pregnant people.

If you are concerned about the privacy risks associated with MCTs, you can create and host your own! There is a step-by-step introductory-level tutorial to create a menstrual tracking application. CycleTracker is a progressive web app (PWA) with a form for the user to enter the start and end date of each period and the entered data is stored in the browser’s localStorage. The PWA can be stored on your device and is fully functional when offline. If you follow the steps in the tutorial, you can create the PWA yourself, and host it locally without ever putting any code online. You can install it on your own device. It works when you're offline or when your local server isn’t running, and will continue running even if you delete the original source code. No form data is submitted to a server and all the data is stored in localStorage over which you have full control.

Because you are coding this PWA yourself, you can add additional features, including features to increase privacy. While the tutorial uses the name "CycleTracker", you can change the name to obfuscate the app's purpose. For example, you could name the app "Manicures" and change the labeling to make it appear that the start date is when you got the manicure and the end date is when your nails needed a re-polish or a press-on nail needed a refill. You control the PWA you develop and the data you enter into it.

If you want to learn how to create PWAs, check out the CycleTracker tutorial. It will take you through all the required steps, including building the basic markup and styles, adding the JavaScript logic, testing locally, and creating a secure connection. It will also give you an opportunity to learn about the components of a PWA manifest file, its iconography, how to define the assets to cache, and how to create a service worker to enable working offline.

If you are going to work thru a tutorial, you might as well work through one that is useful.

OWD projects in H1 2023

2023-07-25T00:00:00Z

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.

Maximizing impact of open documentation for the web platform

2023-07-20T00:00:00Z

The Open Web Docs community believes that freely available open web platform documentation, written by experts, and contributed to by the community is essential to the ongoing health of the web. In this post we outline our relationship with MDN as the current main web presentation of the open source content we contribute to, and share our thoughts on future presentations and uses of this content.

Since its inception in 2021, Open Web Docs has been heavily contributing to mdn/content, which contains the documentation for all features of the web platform, and mdn/browser-compat-data, which contains detailed browser-compatibility data for all features of the web platform. These two repositories are the foundation of Mozilla's MDN Web Docs. These repositories are also used by devdocs.io and caniuse.com, and there are integrations with browser tools, W3C and WHATWG specifications, other developer tools, and IDEs as well.

Open Web Docs believes that contributing to these open source projects drives the biggest impact on web developer documentation worldwide. These repositories build a foundation that helps developers understand web technologies.

Thanks to the clarity of open source licenses and the generosity of open source contributors, mdn/content and mdn/browser-compat-data data can be published anywhere by anyone.

Over the years, several MDN community members have created forks of mdn/content for their own publication and use. While OWD continues to see this pattern as a feature rather than a bug of open source, OWD plans to continue contributing to the upstream mdn/content repository and encourages the community to continue making their own content contributions to the upstream repository in order to sustain the high degree of quality and editorial review necessary for content of this caliber and importance.

The proper presentation of web platform documentation should be driven by the needs of the web development community and what is best for it.

Consuming technical documentation using a website has been the standard practice for many years, but developer needs are changing. Web platform documentation can benefit developers in many other useful ways if it is made available not only through a website but also within context to not interrupt developers in their flow, for example in developer tools (in browser developer tools and extensions, IDEs, and other code editors). Sites and platforms that have specific goals or audience needs in mind might provide only documentation components that are relevant given that context.

Since its founding, Open Web Docs has focused on supporting the quality and coverage of web platform docs as core digital infrastructure, whether they are embedded on websites, platforms suited to specific needs, or within context in new and existing products, like IDEs and code editors. Migrating the docs into markdown was one of our initial steps; our next project on this path will be developing embeddable versions of the HTML and CSS documentation.

We imagine an ecosystem of tools and resources that deliver high-quality, technically correct web platform documentation and data wherever the developer needs it. If your organization or project is interested in embedding open web platform documentation into your tools or services, we would love to hear from you. Please reach out to florian@openwebdocs.org.

Documenting missing interoperable web features

2023-04-26T00:00:00Z

MDN Web Docs is an invaluable information set about the web platform. With about 12,000 pages, it is the most extensive corpus of documents that web developers can rely on when creating websites.

Unfortunately, despite being almost 20 years old, many reference pages still need to be added. We call these missing pages gaps, and even have tools to identify missing content and understand the extent of the issue:

Mozilla's Yari renderer logs missing pages as flaws when it builds a page.
Dominique Hazaël-Massieux, of the W3C, created the mdn-gaps tool which lists all specification features with missing reference documentation.

Why are there gaps on MDN?

Missing pages or gaps slipped in and their number grew organically. Initially, most MDN writers put great effort into documenting Firefox technologies like XUL and XBL, and time was scarce to focus on standardized languages. While CSS, HTML, and JavaScript were well documented, originally the docs for Web APIs were an afterthought. They lived under a DOM hierarchy on MDN. With the advent of HTML as a living standard and CSS module structure initiatives (and later ECMAScript 6), Mozilla Developer Network's focus shifted more from documenting proprietary content to documenting open and interoperable technologies. The shift was progressive, culminating in rebranding the site as MDN Web Docs, the archiving of XUL and XBL docs, and, later, the moving of Firefox Dev Tools documentation to a dedicated website.

Since the early 2010s (and even prior), standard bodies and browser makers have rapidly specified and implemented new APIs. MDN's goal was to document these new features. As these features were web developers' main focus, extensive, accurate, and current documentation was (and continues to be) required. The originally named "HTML5", "CSS3", and "ES6" initiatives allowed MDN to revamp these areas of documentation because there was an interest in positioning the web as a recognized interoperable and modern platform.

The development of the web platform at a greater speed led to the MDN writing community being unable to keep up with documenting all new features while also trying to document the existing foundations of the web platform. This sometimes led to mitigating actions, like listing methods and properties on the interface page but not creating the sub-pages.

Today's gaps mostly fall into three categories:

HTML DOM and SVG DOM features added to the web platform when MDN was still in its infancy;
non-interoperable features: APIs supported by only one or two browser engines;
single properties and methods that were forgotten when the interface was initially documented or added later.

Opportunities created by the Interop initiative

As a collective of writers dedicated to documenting the open web platform, Open Web Docs (OWD) is able to close these gaps. We believe that projects like this can significantly improve in the middle- and long-term health and the longevity of the documentation. We aim to provide complete documentation of the web platform.

For several years now, browser makers have come together to discuss web developer pain points, defining the features that need more attention to improve cross-browser functionality and fixing inconsistencies and issues, ensuring web devs can implement features reliably. This is known as the Interop initiative.

OWD's Steering Committee has determined these projects provide excellent opportunities to revisit the relevant areas of MDN Web Docs documentation. The objective and goal is to have complete documentation for each set of features made interoperable over the year.

Most of the time, this leads to minor changes to the documentation. MDN writers have described the interoperable behavior, such as mentioning when and how browser implementations have diverged; with interoperability, notes about divergence in browser behaviors can be removed.

One of the Interop focus areas this year, interop-2023-forms, is to make HTML forms interoperable. It is a great opportunity to fill some of MDN's gaps. We decided to do the following:

Document all interoperable APIs unrelated to HTML and SVG.
Document all interoperable HTML APIs not part of the DOM (that is, everything in the HTML spec that is not an HTML*Element property or method).
Finally, document all missing HTML*Element features related to <form> (For example, HTMLSelectElement, HTMLInputElement, and HTMLButtonElement properties and methods).

The two first points let us detect any newly interoperable property or method and document it if no one else has already done so. For example, we found gaps after the launch of Safari 16.4 (like WritableStreamDefaultController.signal). These two initial steps will enable us to maintain the completeness of our API reference for interoperable features (once we finish documenting the backlog).

The third step will give us a complete reference for the Forms APIs. It will be synchronized with this year's Interop initiative, where all three engines will be interoperable, fully supporting the Forms APIs.

Current progress

During the first Quarter of 2023, we focused on the first point, documenting all interoperable APIs outside of the HTML and SVG APIs (See our tracking project). We added more than 100 pages to MDN, documenting missing modern features like CSSLayerBlockRule and CSSLayerStatementRule, or old features writers forgot over the years, like XMLHttpRequestUpload.

Already we can detect missed interoperable APIs, unrelated to HTML and SVG DOMs, features that become interoperative: for example, we added the CSSFontFeaturesValuesRule that received support in all major browsers in the first quarter of 2023.

In the second quarter, we are documenting HTML APIs that are part of the HTML DOM, interfaces like ErrorEvent, HTMLAllCollection, or even HTMLOptionsCollection. You can follow our progress in our GitHub tracking issue. In the future, writers will link to these documents. New pages will not have red links, links to non-existent pages, improving the quality of our new documentation. The Constraint Validation API documentation will also be improved this Quarter.

Later this year, we plan to tackle the last point, the missing HTML*Element features related to forms. Overall we plan to add 350 pages this year, about 30% of the overall gaps (for interoperable features).

And all the rest?

After this interop documentation project is complete, almost 700 more interoperable properties and methods will still need to be documented. We are developing plans to tackle the remaining gaps.

SVG documentation could benefit from a similar interop approach. In the first phase, we would like to document fundamental interfaces, like the types: SVGLength, SVGAnimatedLength. We want to call the community for help in the second phase: there are a lot of similar docs to write, like the multitude of SVG filters. Pages with similar structures, though with different examples, are a great opportunity for community involvement.

We will see what will happen, and hopefully, we can report back on progress here!

The great renaming of Web/API

2023-04-13T00:00:00Z

Some projects get to 80% and then take ages to get to "finished", but others take years to get going and then finish in a rush. Our project to retitle pages in MDN's Web/API documentation was the second kind.

The Web/API documentation is the biggest part of MDN, comprising about 6000 pages, a little over half the total. We think it's especially important, as it is the only place that offers a one-stop reference for web developers of all (or nearly all) the JavaScript APIs implemented by browsers.

It includes pages for every method and every property of an interface. The titles of these pages were in the format InterfaceName.methodName():

For a long time, people have raised the issue that this is problematic, because it suggests that something like Document.querySelector() is valid code, which it isn't, of course.

The last time this issue was raised, discussion eventually led, almost 2 years ago, to a proposal for new page titles that was acceptable to everyone.

Finally, last week, we retitled all property, method, constructor, and event pages according to the proposal.

The new titles

The new page titles are longer than the old ones, and are more descriptive of the sort of item being documented:

For the first time, MDN has different titles for static members in Web/API:

This is increasingly important now that we are seeing static and instance members of Web/API interfaces with the same names.

Page titles and page types

This was one of those projects where a major component was consensus-building - making sure all the stakeholders were happy with the new title formats. After that, applying all the titles was "just mechanical". But in reality, the Web/API doc set is so big that retitling all the pages only became practical after we'd put in some infrastructure work.

This work is the "page types" project, in which we've defined a set of "types of things" that MDN's pages cover: for example, CSS property pages, or JavaScript global object pages, or HTML element pages. We then define a front matter key "page-type" whose value represents this type.

With that in place we have a reliable machine-readable way to figure out the kind of thing a page documents, and this enabled us to automate the retitling of about 4000 pages in a couple of days.

Page types don't just make our lives easier, though: we think they will enable other use cases in the future. For example, we'll be able to check that particular types of pages include particular content: for example, that every "CSS shorthand property" page includes a section listing all its longhand properties. Then anyone will be able to query mdn/content to get a complete list of all shorthand properties and their longhands.

It will take us a while to get there, but step by step, we are getting towards a consistent, reliable, structured organization for MDN's reference documentation.

Open Web Docs meetup with Mozilla’s MDN team

2023-02-08T00:00:00Z

This January 18-20, the entire Open Web Docs Technical Writing team and members of the OWD Governing Committee were invited to London to meet with Mozilla’s MDN Team. Mozilla generously sponsored OWD staff's travel and accommodation and Google hosted all of us in their London office. The OWD team was very grateful for this opportunity. Given Open Web Docs was founded during the global covid pandemic, it was the first time we met as a group in person. For some of us, it was our first time meeting each other face-to-face in real life.

The most important project Open Web Docs contributes to is MDN Web Docs. We work closely with Mozilla, our main sponsors Google, Microsoft, Igalia, JetBrains, Canva, our 150+ individual funders, and the larger web community to maintain and innovate on the best documentation site for web developers and designers around the world.

Shared roadmap

In Q4 of 2022, Open Web Docs started working very closely with Mozilla on community coordination and keeping the MDN contribution process running efficiently and effectively. To that end, Mozilla and OWD created a shared and open roadmap for ongoing and planned work. The Open Web Docs team actively collaborates and gives direct input on MDN’s information architecture, compatibility data, content structures, code examples, and other changes coming impacting all sections of the MDN Web Docs site.

With well over 11,000 pages on MDN Web Docs and an ever-evolving Web platform to document, the scope, requirements, and impact of changes for web developers all around the world can be quite a challenge to get right. With all of the expertise from the technical writer and advisory committee teams, we are all coming together on MDN Web Docs to provide web developers with the information they need to create accessible, secure, and performant web pages and applications. It is this mission that drives all of us to collaborate closely, share knowledge, and bring new ideas to the table.

Our shared roadmap will help us to capture significant site changes, from content updates to navigation improvements, and will empower Mozilla, OWD, and our community to implement and execute complex projects together.

Breakout sessions

Many of the discussions in London were about how to collaborate more closely. We also had a few technical deep dive sessions where we were able to discuss in person some of the current projects we are working on. The minutes for these sessions are available on our GitHub. The areas of focus are:

Content lifecycle: We identified the maintenance cost of content additions during planning, defined sunsetting strategies, and discussed ways to separate technical or implementation details from prose that may quickly become outdated.
Information architecture / page types: We talked through the ongoing work to categorize and organize content on the site based on the technology it relates to, and how it works with other technologies.
Discoverability: We discussed how to make it simple for developers to find the information they need while browsing the site, improving the site's search functionality and making it more straightforward and exciting to discover new and related content.
Web platform feature groups: This discussion was about developing a hierarchy that groups platform features across technologies so that developers get a clear picture of whether they can use the features, what they relate to, and the browser and device support for these features.
Code examples: This session covered the plans to make the different types of code examples displayed on MDN easier to maintain and contribute to and ways to simplify the editor that renders them on the page for readers.
BCD (the meeting notes are thin, sorry): This session was about the state of the compatibility data, how to maintain it going forward, and how to guarantee data quality.

Having a meetup with Mozilla, W3C, Google, and Microsoft was an excellent opportunity to discuss ongoing efforts to support web platform documentation for the benefit of web developers & designers worldwide. Our community of technical writers, developers, standards makers, and technology companies continues to do invaluable work for MDN Web Docs. We aim to continue to support documentation as critical digital infrastructure for everyone.

We hope this isn't a one-time event and that we get to meet in person with our partners and people who deeply care about web infrastructure and documentation again when the situation allows. Thanks again to Mozilla and Google for sponsoring us this time! If you want to sponsor Open Web Docs’ next meetup, or want to support us in some other way, get in touch: florian@openwebdocs.org or jory@openwebdocs.org.

Open Web Docs 2022 Q3 report

2022-10-27T00:00:00Z

In 2022 Q3, OWD:

was the major contributor to the mdn/content repository:
- made 1,945 reviews for PRs merged into mdn/content, 63% of all reviews.
- made 284.5 of the PRs made to mdn/content, 11% of the total and twice as many as any other contributor.
led projects to:
- update thousands of JS code samples in MDN to use modern practices.
- integrate markdownlint into the mdn/content repository.
- ensure MDN content and examples follow best practices.
launched a website at https://openwebdocs.org and Carle, the book worm, the new OWD logo.

This report provides an update on Open Web Docs for Q3 2022. It’s split into the following parts:

Goals: a restatement of the overall goals of the organization.
Impact: a summary of day to day contributions to documentation projects.
Projects: a summary of completed projects.

Goals

Just like in 2021, the main focus of Open Web Docs in 2022 has been contributing to MDN Web Docs.

This takes the form of contributions to the main content repositories under the https://github.com/mdn GitHub organization:

mdn/content : the main content repository for MDN Web Docs.
mdn/browser-compat-data : the source of browser compatibility data.
mdn/learning-area : examples supporting the MDN Learning Area.
mdn/interactive-examples : source for MDN’s interactive examples.

Impact

The value of MDN

MDN is an essential resource for web developers. It:

has been cited from Stack Overflow more than 150,000 times in the last 5 years, #2 among all developer documentation sites.
was ranked #2 (behind Stack Overflow) in the State of JS 2021, and State of CSS 2021 surveys.
receives tens of millions of unique visitors every month.

It is therefore essential for the web developer community that MDN continues to be maintained and improved, and the core team continues to be supported in reviewing PRs from the contributor community.

The contributions of Open Web Docs

Open Web Docs is the most significant organization contributing to MDN content maintenance. Of the multiple MDN organization repositories supported by Open Web Docs, the busiest is mdn/content, which contains the source for MDN’s pages. This repository is extremely active:

mdn/content is the 5th most active repository on all of GitHub, as measured by the number of commits/month according to https://git-pulse.github.io/snapshots/.
In Q3 2022, 2,607 PRs were merged into mdn/content from 535 unique contributors.

This report will demonstrate OWD’s contribution to the day-to-day maintenance of mdn/content with two metrics:

Quarterly PRs merged to the mdn/content repository.
Quarterly number of reviews performed on each merged PR to the mdn/content repository.

Both these metrics contain contributions by OWD team members, other organizations that help maintain the repository, and volunteer contributors. Contribution metrics are divided into the following groups:

OWD staff
W3C staff (just Mike Smith at the moment)
Mozilla staff
Other (mostly volunteers, but also people paid by other organizations to work on MDN)

As @queengooborg works for both OWD and Mozilla, her contributions have been evenly split between each organization.

PRs merged to mdn/content

All merged PRs: 2607
OWD: 284.5
W3C: 42
Mozilla: 136.5
Other: 2144

This demonstrates how, of organizations contributing to mdn/content as measured by PR volume, OWD is the biggest contributor. It also shows that mdn/content gets a huge volume of contributions from volunteers: 82.2% of PRs in Q2 were “Other”, which is mostly volunteers.

Reviews of mdn/content PRs

All merged PRs: 3090
OWD: 1942
W3C: 349
Mozilla: 193
Other: 603

The small OWD team provides the largest number of PR reviews to mdn/content, by a significant margin. OWD technical writers performed 63% of all reviews on merged PRs in the quarter.

Projects

In the third quarter of 2022, OWD completed the projects listed below.

Modernization code samples on MDN

During the 2010s, JavaScript evolved substantially as a language. The MDN Web Docs JavaScript documentation dates back to ES3. The docs were completely revamped around 2015 (for ES6); however, since then, the docs didn’t see a major update throughout. New features were documented and used latest best practices, but docs for older features mostly demonstrated best practices of the time.

MDN Web API code samples were in a similar situation. They were partly updated for ES5 and ES6, however they weren't modernized consistently on all pages, which often lead to a perception of old school and inaccurate code snippets.

MDN Web Docs' primary audience is web developers. We want to have examples that can be used in most professional projects. Not using ES6+ features in 2022 is problematic as:

Modern JavaScript is now easier to read and write.
Most projects use modern JavaScript or transpilers.
Some patterns used in the 2000s are now considered anti-patterns to avoid.

In Q3 2022, we agreed which modern JS features to use on MDN, then applied them to most of our static examples.

We proceeded in three phases.

First, we drove an open discussion to define JS features that are in common use now. The discussion was vivid and civil and was noticed in the JS community. The newsletter “JS Weekly” had a mention about it in one of its episodes, and 19 people participated in the discussion with a total of 81 messages; much more than usual MDN discussions. In that discussion, a consensus was reached about which JS features to use. Examples are, among other things:
- using for…of or .forEach instead of classic for(;;) structure,
- let and const instead of var
- template literals,
- arrow functions
In the second phase, we applied the consensus to most static examples on MDN. We created a community of contributors to help us. With the help of more than 20 contributors and more than 200 PRs, we updated most of the 16332 static examples on 6396 pages on MDN. We limited ourselves to the most common features. This was enough to change how MDN examples are perceived: from old-style coding examples, they are now modern-style examples.
Finally, the third phase consisted of updating MDN's JS coding guidelines. We also worked by consensus between all maintainers of MDN and created a single PR with 298 comments. This allowed us to communicate the new style to most maintainers but also to be able to refer to agreed conventions when divergences occur.

MDN is so large that there is still a lot to do after this project. For now, we focused on static examples on MDN pages. MDN also has interactive examples and a corpus of external examples (js-examples, css-examples, dom-examples, …); these examples should also be updated to the new guidelines. We hope to do this in the future. Still, as this is a significant piece of work, we would like to group this with a few other modernization activities that are needed: we would like to lint these examples with ESlint (to detect errors), avoid outdated APIs (like using the Fetch API instead of XHR), as well as fix any accessibility and semantic issues. We think it is a good idea to triage these structural issues, drive discussions about best practices and then apply the changes to all MDN pages.

To sum up, we renovated all static examples on MDN. They now use modern JS and can be more easily copied and pasted into real projects. They also teach better practices to developers. Working with the community on this project has been gratifying, and it helped us finish the whole project in a quarter when otherwise these mass-changes on thousands of MDN pages can take much longer.

Linting Markdown

The migration of MDN pages to Markdown improved the quality of MDN pages and its maintainability. In comparison to HTML, Markdown is easier to read on GitHub and leads to simpler diffs when reviewing PRs. It is also a lot more concise, resulting in more homogeneity of the source of MDN documents.

This homogeneity allows us to use linters to enforce a better structural and typographic coherence.

In Q3 2022, we worked with the community to integrate the most common Markdown linter, markdownlint, into the writing workflow. We were particularly cautious, as it is the first linter we added to the writing process. Tooling should help writers and first time contributors, not annoy them.

To simplify editing for writers, we want Markdownlint to autocorrect all what can be auto-corrected. That way, writers don't need to know all the details of using Markdown (like empty lines before lists) or of our writing guidelines (like using underscore for italics, and two stars for bold)

The challenge resides in integrating the linting with the two workflows:

Editing using the GitHub UI.
Editing locally and pushing the result via git.

When editing locally, most editors (like VSCode) warn writers when they make an error. When using the online GitHub UI, there is unfortunately no indication when a contributor doesn't follow the markdownlint rules.

Our challenge was to find a solution for both ways.

To solve this, we needed three pieces:

A markdownlint bot, running daily, which fixes markdownlint errors automatically, or notifies about non-auto-fixable errors.
A test in the GitHub CI, flagging the errors in the PR, allowing writers to fix them manually if they want.
markdownlint integration with Husky so each time a commit is created locally, auto-fixable errors can be fixed without contributors having to do anything.

We have a few future improvements to perform still: we want to add more rules, like preventing images without alt texts. In order to do so, we need to fix all the existing problems to make sure the current HEAD passes with zero errors, and then update our config files to enable the test.

Overall, markdownlint integration went smoothly, to the point where the daily markdownlint bot has very errors to catch. This improves the quality of the source of the docs, and we will be able to add more rules in the future.

Best practices: emulate what we teach

As noted in the value of MDN, MDN is an essential resource for web developers, second only to stack overflow, and the second most important resource for stack overflow. A large percentage of Stack Overflow answers are code snippets copied directly from MDN. MDN is itself a learning resource for new and senior developers alike. For these reasons, and more, it’s important that all examples demonstrate accessible semantic best practices.

To this end, several objectives to reach this best practices goal, including (but not limited to).

Ensuring <html> elements are preceded by a doctype.
Ensuring <html> elements include a lang attribute
Including a charset <meta> tag in all full header examples
Including the viewport <meta> tag in all full header examples
Ensure the <abbr> element is used correctly, removing the title attribute from the majority of occurrences.
Ensuring any included <b> and <i> elements are solely presentational in nature.
Removed browser prefixes from supported CSS properties; updating all examples that included prefixes.
Removed unnecessary type attributes, such as type=”text/css” and type=”text/javascript”.
Removed most references to HTML5 and CSS3, as both HTML and CSS are living standards without version numbers

Work is ongoing to ensure <input> examples that contain more than just the type attribute include recommended attributes, such as name and value on checkboxes, radio buttons, and hidden inputs and ensure examples that contain form controls have a label associated with the form control.

At the beginning of the quarter, there were 404 empty alt attributes in markdown code, and over 100 images with either the name of the image as the alt attribute value or missing alt attributes in an HTML <img> code block. Open Web Docs crowd sourced fixing over 500 alt attributes. At the end of the quarter, there are less than 125 left.

While working on the best practices goal, a lot of outdated content was discovered and updated. Many instances for “when supported” and “new to the browser” language were deleted, and the surrounding content updated to remove any ‘experimental’ feel of well supported features.

Improving MDN's CSS formal syntax

2022-10-11T00:00:00Z

If you've spent much time with the CSS docs on MDN, you've probably seen the "Formal syntax" section in the CSS property reference pages. When we ask developers what they think of this part of the docs, most of them say something like "I have no idea what this means". This used to be my reaction too, but now I think it can be extremely useful. CSS properties can have complex syntax, and explaining it in prose can be really hard. Once you've learned a few rules, the formal syntax gives you a very precise description of the syntax in a very concise manner.

Until recently, though, there were two big problems with the way MDN represented formal syntax.

The first problem was presentation: the macro that rendered the formal syntax as HTML tended to render it as a wall of text, making it hard to read and scarier than strictly necessary:

The second problem was about data quality. Although the formal syntax should match the syntax in the specifications, MDN maintained its own copy of the data in a separate repository, mdn/data. We often weren’t able to keep this up to date with the specification, and as a result, users of MDN would see inaccurate or outdated syntax.

Enter css-tree and @webref/css

Our solution to these problems rested heavily on two amazing open source packages.

The css-tree package enabled us to generate an AST for a formal syntax definition, making it much easier to render it in a more usable form. In particular, we have added syntax highlighting and pretty-printing. Here’s that syntax for background with the updated code:

Next, we replaced mdn/data as a data source with the @webref/css package, developed and maintained by our friends at the W3C. This scrapes the syntax directly from the specifications, so we know it will be fresh.

The collection of webref packages contains lots of interesting structured content extracted from the specs, and we think there are potentially many ways we can use it to make MDN more accurate and maintainable. Using it for formal syntax is, we hope, only the start.

Wrapping up

Huge thanks go to @lahmatiy, the developer of css-tree, and @tidoust for his work on webref and his patient guidance in navigating the CSS specifications.

We're interested to hear what you think too. If you have ideas for how we can make the formal syntax more useful and approachable, or how we can use structured content from the specs to improve MDN, please let us know!

Announcing the launch of our new logo and website

2022-10-04T00:00:00Z

Open Web Docs is pleased to announce the launch of a new website, a new logo, and Carle, the new Open Web Docs mascot.

Steering committee member and Black Girls Tech founder, Lola Odelola, led the OWD rebranding efforts. She coordinated the development of the new OWD mascot and logo and built the new website.

Carle, pronounced kahr-lee, the OWD mascot, was designed by Vladimir Grigoriev, a design lead at JetBrains. Carle is a bookworm! She’s named after the beloved children’s book author, Eric Carle. Carle personifies the OWD brand and is super memorable.

"I definitely love the new logo. It makes me happy every time I see it, and it perfectly reflects the marketing tone we started defining a year ago of fun, inclusion, accuracy, kindness, and goofiness. Hats off to Lola and Vladimir, and a huge thank you to JetBrains as well!" remarked Estelle Weyl, OWD staff writer.

While Carle is usually smiling, she has five other facial reactions, enabling using slightly modified logos with different moods for different purposes. Her main color is a fantastic purple orchid, #B448FF.

Using the new logo, the OpenCollective OWD site, and the purple orchid color as a starting point, Lola built OWD a new site in 11ty, creating a site with both light and dark themes. Lola claims not to be a designer. We beg to differ. Her two themes are fantastic. The light theme has a lot of white space, is simple and friendly, and is easy to navigate. The dark theme is too. But, unlike many dark site versions, the colors aren’t inverted. Rather, the dark theme uses several gorgeous shades of purple.

After a year of discussing a rebrand, we are so thankful to Lola and Vladimir for their hard work and dedication. We are delighted to officially announce the launch. The new site is available at the same URL as before: OpenWebDocs.org. Like everything OWD, the site is open source and available on Github.

The new website provides our visitors with clear, easy way to learn about Open Web Docs, who we are, what we do, and who funds us. You can learn about what we’ve accomplished and how you can get involved, including sponsoring us and becoming a member. We have a page about our open source maintainers and steering and governing committees and a page highlighting our sponsors and funders. The new website also includes OWD's accomplishments for the past year and a blog with more details about many of our projects.

We will continue to update our site with helpful information, articles, announcements, and project successes in the blog section.

We would like to thank Lola and Vladimir who gave their time, energy, and talents to make this site and our branding what it is.

For any questions, suggestions, feedback, or comments, please send us questions via the Open Collective contact form, love on Twitter, website feedback via GitHub or content ideas via our project proposal form.

Apple joins the Open Web Docs Steering Committee

2022-09-05T00:00:00Z

We are happy to welcome Apple to the Steering Committee of Open Web Docs! They are joining our mission to document the web for developers.

The Steering Committee is responsible for deciding what Open Web Docs should work on and with what priorities, as illustrated by our 2022 goals.

We’re excited to have representatives from all major web browser vendors in the Steering Committee of Open Web Docs, providing us with support so we can cater to and help developers globally to build better documentation on the web across all browsers.

Originally published at https://opencollective.com/open-web-docs/updates/apple-joins-the-open-web-docs-steering-committee

Open Web Docs 2022 Q2 report

2022-07-01T00:00:00Z

This report provides an update on Open Web Docs for the second quarter of 2022. It’s split into the following parts:

Goals: a restatement of the overall goals of the organization
Impact: a summary of day to day contributions to documentation projects.
Projects: a summary of completed projects
Community: activities in which OWD staff have mentored volunteers on docs projects

Goals

The main focus of Open Web Docs in 2022 has been contributing to MDN Web Docs.

This takes the form of contributions to the main content repositories under the https://github.com/mdn GitHub organization:

https://github.com/mdn/content : the main content repository for MDN Web Docs
https://github.com/mdn/browser-compat-data : the source of browser compatibility data
https://github.com/mdn/learning-area : examples supporting the MDN Learning Area
https://github.com/mdn/interactive-examples : source for MDN’s interactive examples

Impact

The value of MDN

MDN is an essential resource for web developers. It:

has been linked from Stack Overflow more than 150,000 times in the last 5 years, #2 among all developer documentation sites
was ranked #2 (behind Stack Overflow) in the State of JS 2021 and State of CSS 2021 surveys

The main MDN repositories, especially mdn/content, are extremely active. In Q2 2022, 2475 PRs were merged into mdn/content from 507 different users.

It is therefore essential for the web developer community that the MDN core team continues to:

contribute to MDN to maintain and improve it
review PRs from the contributor community.

The contribution of Open Web Docs

On a daily basis, the Open Web Docs staff team contributes to the open-source repositories of the MDN Web Docs GitHub organization. The contributions can come in many forms (creating pull requests, filing issues, reviewing pull requests, participating in discussions, triaging issues) on a handful of repositories that are foundational to MDN Web Docs.

In this section we’ll see that Open Web Docs is the most significant organization contributing to MDN content maintenance.

We’ll present metrics for the two busiest repositories on the MDN organization:

mdn/content, which contains the source for MDN’s pages
mdn/browser-compat-data, which contains compatibility data used to power compatibility tables on MDN and other tools including caniuse.com, IntelliJ WebStorm and Visual Studio Code

For each repository we’ll present two metrics:

The number of PRs merged to that repository in the quarter.
The number of reviews performed on each merged PR to that repository in the quarter.

For both these metrics, we’ll not just include numbers for OWD, but also for the other organizations that help maintain the repository, and for volunteer contributors.

mdn/content

This is the main repository under the MDN organization on GitHub and is extremely active, receiving 500-700 pull requests every month, from about 200 distinct contributors. The chart below shows the total number of PRs merged to mdn/content each month since the start of 2021:

The spike in May 2022 is from the Writing Day, which is described below under “Community”.

Here we’ve split contributions into the following groups:

OWD staff
W3C staff (this is actually just Mike Smith)
Mozilla staff
Other (mostly volunteers, but also people paid by other organizations to work on MDN)

Note that @queengooborg works for both OWD and Mozilla, so we have simply split her contributions between each organization.

PRs merged to mdn/content

All merged PRs: 2475.

OWD	W3C	Mozilla	Other
461.5	80	117.5	1816

This shows that OWD is the biggest single organization contributing to mdn/content, as measured by PR volume. It also shows that mdn/content gets a huge volume of contributions from volunteers: 73.4% of PRs in Q2 were “Other”, which is mostly volunteers.

Reviews on merged PRs to mdn/content

All reviews: 2872

OWD	W3C	Mozilla	Other
2118.5	334	2867.5	133

This shows also shows that 73.8% of all PR reviews to mdn/content in Q2 were made by OWD staff. We should especially note Jean-Yves Perrier here, who made 1333 PR reviews in this quarter!

mdn/browser-compat-data

This is the second-busiest repository in the MDN organization on GitHub. It contains machine-readable JSON files that describe browser support for web platform features. This data is used not only in MDN but also by other sites like caniuse.com.

For this repository we’ve split contributions into four groups:

OWD staff
Google staff
Mozilla staff
Other (mostly volunteers, but also people paid by other organizations to work on MDN)

Note that for browser-compat-data we have not included W3C, as they are not a major contributor to this repository. Instead we have included Google who are a significant contributor.

Note that @queengooborg works for both OWD and Mozilla, so as before, we have simply split her contributions between each organization.

PRs merged to mdn/browser-compat-data

All merged PRs: 778

OWD	Google	Mozilla	Other
239.5	58	259.5	221

Reviews on merged PRs to mdn/browser-compat-data

All reviews: 688

OWD	Google	Mozilla	Other
186	230	154	118

This shows that OWD is a substantial contributor to browser-compat-data. It’s worth mentioning though that by far the biggest contributor to this repo, by both commit count and review count, was @queengooborg.

Projects

In the second quarter of 2022 we completed the projects listed below.

Web/API page types

See the project proposal.

In Q2 we started a project to classify MDN reference pages and represent the classification in a machine-readable way. This is a piece of infrastructure work that will enable us to have more consistent and correct reference documentation.

For example, we need to:

Define the type of sidebar that a page ought to have
Define the organization of a reference page, including the page elements that should appear (such as spec URLs or BCD tables) and the order in which they should appear
Define the format that page titles should have.

All these features depend on reliably identifying the kind of thing that a page documents. Up to now we have used page tags for this, but their semantics isn’t precisely defined and (partly as a result of this) the tags are often incorrectly applied.

So we decided to define a dedicated front matter item to represent the page type, across all our most important docs.

In Q2 we completed this project for the Web/API docs, which represent about half the total number of pages on MDN. We defined 12 page types that exist in the Web/API docs and added the correct front matter key to all 6000 Web/API pages.

The most immediate impact of this is that we will be able to fix the titles of Web/API pages on MDN, as discussed in https://github.com/mdn/content/discussions/5121 and also requested in https://github.com/openwebdocs/project/issues/104 . We hope that this will be a Q3 project.

Better CSS formal syntax

MDN’s reference pages for CSS properties include a section which contains the formal syntax for the property. This is potentially a very useful part of the page, giving a concise and precise definition of the property’s syntax.

However, it’s long been problematic.

First, the way it is formatted makes it very hard to read. For example, here’s part of the syntax for background:

Second, although the formal syntax should match the syntax in the specifications, we generated formal syntax in MDN from a separate repository, mdn/data. We often weren’t able to keep this up to date with the specification, and as a result, users of MDN would see inaccurate or outdated syntax.

In this project we’ve tackled both of these problems.

First, we’ve used the css-tree package to parse formal syntax definitions into an AST, which makes it much easier to render it in a more usable form. In particular, we have added syntax highlighting and pretty-printing. Here’s that syntax for background with the updated code:

Second, we’ve used the W3C’s webref/css package to supply the formal syntax. This package scrapes formal syntax directly from the specifications, so we can be confident that it will always match the version in the specs.

The webref package contains lots of interesting structured content extracted from the specs, and we think there’s potentially a big role to play for webref in making MDN more accurate and maintainable. Using it for formal syntax is, we hope, only the start.

Thanks especially go to @lahmatiy, the developer of css-tree, and @tidoust for his work on webref and his invaluable guidance in navigating the CSS specifications.

Cascade Layers

Cascade Layers, which allows developers to define contained layers of specificity, recently landed in all browsers. While “cascade” is the C in CSS, many developers don’t understand the cascade or how specificity, cascade, and inheritance work. So much so, that specificity is the top CSS page.

This quarter we rewrote existing documentation, including a full re-write of Introducing the CSS Cascade and Specificity (the most visited CSS page), including creating new !important documentation and adding layers to mentions of cascade, @import, etc., and switching how specificity weight is defined throughout MDN documentation.

Community

One of our goals is to collaborate with and mentor volunteers in contributing to open source documentation. In this section we’ll describe some of these collaborative projects.

Write the Docs Writing Day

In May we hosted a table at the Writing Day for the Write the Docs Portland conference. We were joined by about 20 volunteers, many of whom were quite new to Git and GitHub. We introduced MDN Web Docs and explained how people could contribute using the GitHub UI. Our focus was to replace usages of var in MDN’s JavaScript documentation with let or const. During the day our volunteers filed PRs cleaning var from about 250 pages in the JavaScript documentation, out of about 300 pages in which it appeared. For many of the volunteers this was a first contribution using GitHub.

There are more details in our blog post: https://opencollective.com/open-web-docs/updates/write-the-docs-writing-day .

Cleaning var from Web/API

After Writing Day we started a community project to remove var from the Web/API documentation. We filed a tracking bug: https://github.com/mdn/content/issues/16662 to coordinate the work. We’ve provided ongoing review and mentoring for volunteers, who in Q2 have removed var from almost 500 pages in Web/API.

Write the Docs Writing Day

2022-05-23T00:00:00Z

Open Web Docs hosted a session at the Writing Day during the Portland 2022 edition of the Write the Docs conference. In this post we'll talk about what we worked on and how it went.

Write the Docs is a conference for people involved with all aspects of documentation, including writers, developers, editors, information architects and so on. It happens twice a year, once in Portland and once in Prague. The Sunday before the main conference is the "Writing Day", when people come to work on open source documentation projects.

Open Web Docs loves Write the Docs, in part because it's extremely inclusive, welcoming people from all kinds of disciplines that relate to documentation. This makes it an interesting place, where everyone knows different things, and everyone can learn something. We sponsored the Portland 2022 Write the Docs and hosted a session at the Writing Day for people who wanted to contribute to MDN.

Preparation

We prepared a few projects for participants. The two that resonated most with people were:

removing var from our JavaScript documentation
fixing sidebars in the Web API documentation.

Removing var

In the old days JavaScript used var to declare variables. For a long time now this is considered bad practice, and it's recommended that people should use let or const instead. In early 2022 Open Web Docs updated the JavaScript Learn documentation on MDN to replace usages of var in code examples, but we didn't yet update the JavaScript reference documentation.

In preparation for the Writing Day we made a list of 300 pages that mentioned var, and asked attendees to replace it with let or const as appropriate.

Fixing sidebars

On MDN sidebars are added to pages using macros. We made a list of all the pages under Web APIs that were missing a sidebar, and asked attendees to add the correct macro call. This amounted to about 50 pages.

On the day

From Open Web Docs, Will Bamberg, Estelle Weyl and Queen Vinyl Da.i’gyu-Kazotetsu were there to host the session, and we were joined by about 20 volunteers. We walked through the process of editing a page on MDN using the GitHub UI and explained the activities.

From then the session was very quiet, as volunteers worked hard all day filing GitHub PRs to fix the problems, and OWD staff reviewed them and answered the occasional question.

Many people stayed for the whole day and filed dozens of PRs.

At the end of it:

we cleaned var from 254 pages in the JavaScript reference, out of 300 pages that were using it
we added sidebars to all pages under Web APIs that were missing a sidebar, with the exception of only four, which all need more complex fixes.

Especially the removal of var is a substantial improvement to MDN Web Docs. Our own documentation advises against the use of var, so it's very misleading for our JavaScript examples to use it, and the work of our volunteers made a big step towards removing it completely.

What we learned

We learned, first, what we already knew, that Write the Docs attendees are welcoming, engaging, generous, and generally a pleasure to work with.

Many attendees did not have previous experience of working with GitHub, the PR model, or docs under source control. It was helpful to have an introductory session about this. As it turned out, the technical side went smoothly. People quickly understood how to use the tools and were able to be very productive. It might have been worth spending more time up front exploring other tools, which would enable people to submit fewer, larger PRs: a limitation of the GitHub UI is that each PR can only include one file. In general it's worth organizers explicitly considering what they are giving back to attendees in terms of learning how to use these tools.

Successful projects tend to be ones that are well-defined and fine-grained, meaning that even a small contribution can be complete and useful. Next time we would like to prepare some projects which allow volunteers to engage more deeply with the content, but it's challenging to do that while still keeping projects accessible.

What's next?

We've felt quite inspired by the progress our volunteers made towards cleaning var from our documentation, and have filed a tracking issue to finish removing var from our JavaScript pages, and another one to remove it from our Web/API pages, so that volunteers and staff can finish the work.

We'd also like to consider how we could help writers who are new to Git and GitHub learn how to work with these tools.

Thanks!

Finally of course we'd like to thank Write the Docs, for enabling such a great community, and the volunteers who spent their Sunday helping to improve MDN:

Open Web Docs 2022 Q1 report

2022-04-20T00:00:00Z

This report provides an update on Open Web Docs for the first quarter of 2022. It’s split into the following parts:

Goals: a restatement of the overall goals of the organization
Staff: an update on staffing changes
Impact: a summary of day to day contributions to documentation projects.
Projects: a summary of completed projects

Goals

Just like in 2021, the main focus of Open Web Docs in 2022 has been contributing to MDN Web Docs.

This takes the form of contributions to the main content repositories under the https://github.com/mdn GitHub organization:

https://github.com/mdn/content : the main content repository for MDN Web Docs
https://github.com/mdn/browser-compat-data : the source of browser compatibility data
https://github.com/mdn/learning-area : examples supporting the MDN Learning Area
https://github.com/mdn/interactive-examples : source for MDN’s interactive examples

Staff

At the start of 2022 we were delighted to welcome a new part-time team member, Queen Vinyl Da.i'gyu-Kazotetsu. Vinyl has been a major contributor to the BCD project for several years, initially as a volunteer but most recently as a Google contractor. She is the number #1 contributor to the BCD repository. We’re pleased to have someone to help maintain this essential part of the web docs puzzle.

Impact

In this section, we’ll present metrics for the two busiest repositories on the MDN organization:

https://github.com/mdn/content, which contains the source for MDN’s pages
https://github.com/mdn/browser-compat-data, which contains compatibility data used to power compatibility tables on MDN and other tools including caniuse.com

For each repository we’ll present two metrics:

The number of PRs merged to that repository in the quarter.
The number of reviews performed on each merged PR to that repository in the quarter.

For both these metrics, we’ll not just include numbers for OWD, but also for the other organizations that help maintain the repository, and for volunteer contributors.

mdn/content

This is the main repository under the MDN organization on GitHub and is extremely active, receiving 500-700 pull requests every month, from about 200 distinct contributors.

Here we’ve split contributions into the following groups:

OWD staff
W3C staff (this is actually just Mike Smith)
Mozilla staff
Other (mostly volunteers, but also people paid by other organizations to work on MDN)

PRs merged to mdn/content

OWD	W3C	Mozilla	Other
295	115	101	1198

This shows that OWD is the biggest single organization contributing to mdn/content, as measured by PR volume. It also shows that mdn/content gets a huge volume of contributions from volunteers: 70% of PRs in Q1 were “Other”, which is mostly volunteers.

Reviews of PRs merged to mdn/content

OWD	W3C	Mozilla	Other
1096	510	201	163

mdn/browser-compat-data

For this repository we’ve split contributions into four groups:

OWD staff
Google staff
Mozilla staff
Other (mostly volunteers, but also people paid by other organizations to work on MDN)

Note that for browser-compat-data we have not included W3C, as they are not a major contributor to this repository. Instead we have included Google who are a significant contributor.

PRs merged to mdn/browser-compat-data

OWD	Google	Mozilla	Other
268	39	71	201

Reviews of PRs merged to mdn/browser-compat-data

OWD	Google	Mozilla	Other
304	217	131	36

Projects

In the first quarter of 2022 we continued to work on the projects that were ranked most highly in our Q4 2021 planning. We completed the projects listed below.

Modernize the JavaScript Learning Area

See the project proposal.

The Learning Area is the main resource MDN offers for people to learn web development. The JavaScript section of this guide consists of a number of modules, covering:

fundamentals such as variables, loops, strings, arrays, and functions
objects and object-oriented programming in JavaScript
asynchronous programming
an introduction to some of the main Web APIs.

The JavaScript Learning Area is a popular part of MDN and many people new to Web development take the course. However, when it was written in 2017, many features and techniques that are now mainstream modern JavaScript still seemed too new to recommend without reservation, and many features were not covered at all. Since then it has never been systematically updated to recommend modern JS features and techniques.

In this project, we assessed the complete JavaScript Learning Area and updated it for 2022. This included consistently teaching modern features and practices, and updating all example code to use them. In the process, we completely rewrote the “Objects” and “Async” modules and made many smaller changes throughout.

Thanks to everyone who engaged with this project to discuss how we should rework the content and reviewed PRs, especially Ruth John, Mike Smith, Hamish Willee, and Florian Scholz. Special thanks to Michael Koch who's done a fantastic job of helping people through the Learning Area courses and maintaining its content.

Rewriting reference pages for all web platform events

See the project proposal.

Web developers work with web platform events on a daily basis. A lot of the interactivity of a website is achieved by listening and reacting to events. There are many specifications that define the web platform API surface and most of them define events. It is not easy to figure out available events on a specific object as the specifications do not always list them clearly or there are multiple specifications each defining an object and its event only partially. On MDN Web Docs, we try to list every event that can be fired at a specific object making it an essential reference for web developers who work with events.

There are three ways to set an event listener on an object:

using a property of the form onXYZ,
using the addEventListener() method, or
using an HTML content attribute in case the object is an HTML element, like <body onload=””>.

Over the years, different MDN contributors created different pages for all three ways to listen to the same event. This turned out to be problematic and repetitive. Information was duplicated and updates happened on one page but not on another. This also led to duplicate browser compatibility information that was inconsistent and contradictory.

Two additional things made the MDN event reference worse and lead to further page duplication and inconsistencies:

Event bubbling, which makes events available on a whole hierarchy of objects
Mixins that define the same event handlers on numerous objects.

The goal of this Open Web Docs project was to avoid event page duplication, as well as to harmonize and simplify the description of events in the context of their target objects.

The first part of this project was to update the compatibility data in BCD with the idea that only one entry, named eventname_event is added to the BCD data going forward. There is no longer a separate entry for the onEventName property. In case of bubbling events, the entry is placed on the top-most interface of the hierarchy. And for mixins (which we had already mostly removed from MDN and BCD in 2021), the event support is documented on the most relevant interface (e.g. Window for WindowEventHandlers).

The second part, which happened parallel to the first part, was to update the MDN pages to match the idea of a single place for an event just like in the browser compatibility data. We moved a lot of pages around and adapted the content. All existing onEventName are now redirected to the eventName_event page that has a syntax section that describes both ways of setting an event listener. The new page structure for event pages was agreed on in an mdn/content discussion. We also adapted the interface pages. Now, they list all events that can be caught on an object implementing it, including events that can bubble.

We eliminated roughly 300-400 pages of contradictory information by documenting events in this new, consistent way.

Going forward, this creates a good foundation and a more structured approach to documenting more events on MDN in the future. MDN contributors now understand better how to document events and for readers, the relevant information is more concise and presented in a much clearer way. In the future, we would like to define this MDN documentation page type for web platform events even more so that tooling around mdn/content and mdn/browser-compat-data can work with it smoothly.

This project was driven by Florian Scholz, Jean-Yves Perrier, and Vinyl Da.i'gyu-Kazotetsu. We like to note that it would have been impossible to do this project without the help of Philip Jägenstedt, who originally proposed many of these changes. Philip not only provided us with his deep web platform knowledge, his input was also essential to solve many weird edge cases and to understand some legacy behaviors that made the rest of us want to give up. Thank you, Philip!

WAI-ARIA Web Accessibility Documentation

In 2018, a group of folks met for a “Hack-on-MDN in London, UK to work on accessibility documentation. Estelle organized another Accessibility Hack on MDN at the Access U, an accessibility conference in Austin Texas. During these two sessions, excellent accessibility documentation was written, especially with regard to Web Content Accessibility Guidelines. However, the WAI-ARIA ( Accessible Rich Internet Applications ) specification’s roles, states, and properties were not fully addressed and were never updated. This has been resolved.

While HTML is designed to be accessible, developers often use non-semantic elements to recreate form controls and create complex UI features not addressed by existing HTML elements. To make the web content fully accessible, ARIA roles, states and properties can be added to provide semantic information about widgets, structures, and behaviors, enabling screen readers and other assistive technologies to convey appropriate information to users of these technologies.

Over the last two and a half quarters, the WAI-ARIA specification has been documented on MDN. The specification provides an ontology of roles, states, and properties that define accessible user interface elements and can be used to improve the accessibility and interoperability of web content and applications enabling developers to properly convey user interface behaviors and structural information to assistive technologies.

While the new documentation of the ARIA roles and attributes covers everything in the specification, it also provides detailed descriptions on when each role or attribute should be used and, importantly, not used. After all, the first rule of ARIA is "If you can use a native HTML element or attribute with the semantics and behavior you require already built-in, instead of repurposing an element and adding an ARIA role, state or property to make it accessible, then do so."

Each MDN role page provides a description, explanation of required and optional states and properties, keyboard interactions that need to be programmed, and examples. The MDN role documentation provides information beyond what is contained in the WAI-ARI spec, including how to avoid needing to use ARIA (what HTML elements provide optimal semantics), considerations of visual requirements as widgets need to be usable for everyone, not just screen readers. Considerations for mouse users, keyboard users, and sighted users who also use screen readers for any number of reasons were included when needed.

The project started in Q3 2021 when we documented basic ARIA roles, including landmark roles, window roles, abstract roles, and document structure roles. In Q4 2021, we documented 53 ARIA states and properties. In Q1 or 2022, we revisited ARIA roles, tackling the more complex widget and composite widget roles, creating 29 PRs for 42 tasks. See Project: Complete the ARIA Roles section for more details.

A huge thank you to Eric Bailey and Scott O’Hara for reviewing all the PRs and using their expertise to provide invaluable feedback.

MDN => Markdown

2022-04-19T00:00:00Z

In 2021, the Open Web Docs team, with help from Mozilla, the W3C, and the wider web docs community, converted the authoring format for MDN Web Docs - all 11,000 pages of it - from HTML to Markdown. In this post we'll talk about why we did it, how we did it, and how it turned out.

HTML soup

Before 2020, MDN was a Wiki, and contributors edited pages using a web-based WYSIWYG HTML editor. This made it easy to make casual contributions: people could edit text and apply simple formatting, like bold or code, without having to edit the underlying HTML. But a WYSIWYG editor is not well-suited to more complex edits, and authors often had to edit the underlying HTML source directly. Also, because the underlying source was hidden by default, HTML cruft, like <span id="486uw3y3"> crept into the source, often from authors pasting HTML from another rich editing environment into the MDN WYSIWYG editor.

In 2020, MDN replaced the old Wiki with a new platform in which the source for the docs was stored in a GitHub repository as a collection of HTML files, and this was built into web pages by the Yari code. This had several major advantages, but it meant that the old WYSIWYG editor was no more. Instead, all authors had to edit MDN pages as raw HTML documents.

For technical writers, HTML is hard to write and hard to review. It's easy to make mistakes like missing closing tags or getting the nesting wrong, and it's hard for reviewers to spot these kinds of mistakes. Also, we had to escape HTML tags in any example code we wrote, which is difficult and error-prone. For example, here's a code sample from the page on <dl>:

<pre class="brush: html">&lt;dl&gt;
  &lt;dt&gt;Name&lt;/dt&gt;
  &lt;dd&gt;Godzilla&lt;/dd&gt;
  &lt;dt&gt;Born&lt;/dt&gt;
  &lt;dd&gt;1952&lt;/dd&gt;
  &lt;dt&gt;Birthplace&lt;/dt&gt;
  &lt;dd&gt;Japan&lt;/dd&gt;
  &lt;dt&gt;Color&lt;/dt&gt;
  &lt;dd&gt;Green&lt;/dd&gt;
&lt;/dl&gt;
</pre>

In practice, this makes writers concentrate so much on the markup that it's hard to concentrate on the writing itself.

Also, authors were faced with the result of 15 years of people pasting rich content into the WYSIWYG editor, resulting in source like this:

<pre class="brush: js"><span class="kd">const</span> <span class="nx">element</span>
<span class="o">=</span> <span class="nx">driver</span><span class="p">.</span>
<span class="nx">findElement</span><span class="p">(</span><span class="nx">By</span>
<span class="p">.</span><span class="nx">id</span><span class="p">(</span>
<span class="s1">'myElementId'</span><span class="p">));</span></pre>

It was clear that for the long-term health of MDN, we needed a better authoring experience than this, both for volunteer contributors and for full-time staff writers.

Choosing a format, part 1 - Markdown

Replacing HTML as the authoring format for MDN wasn't a new idea: we had discussed it many times in the last few years. We had considered both AsciiDoc and reStructuredText and in many ways these formats are superior to Markdown: they are more powerful, they support semantic markup, and they have extensibility built in.

Instead of these, we chose Markdown, because Markdown is such a widely used and supported format. This gives us two major advantages:

almost everyone coming to MDN is going to understand Markdown well enough to contribute right away. Even though many MDN contributions need an understanding of the (sometimes extreme!) complexity of MDN, many contributions do not, and Markdown makes these contributions as easy as possible.
there's great and often seamless tool support for Markdown. Most modern code editors have Markdown preview built in. Prettier has support for Markdown (and even for code samples embedded in Markdown). GitHub can display rich diffs for Markdown.

Choosing a format, part 2 - but which Markdown?

One difficulty with Markdown is that there isn't a single Markdown. There are multiple incompatible versions, each featuring different extensions to the basic syntax. It was observed early on that we could make a lossless and entirely automatic conversion from HTML to Markdown, by using syntax extensions for components such as class and id attributes.

This would have made the project go much quicker, because we would not have had to clean up the source content. But it would have delivered much less value, precisely because we would not have cleaned up the source content. The main purpose of this project was to have readable source files.

This pushed us towards a minimalist approach, in which we would:

choose a baseline flavour of Markdown
analyse our current files to figure out which extensions we needed
decide on a syntax for the extensions
update our sources to clean any HTML syntax that we didn't want to take into our future

Choosing a format, part 3 - the gory details

For the baseline we chose GitHub-Flavored Markdown (GFM). This is well-supported and has a good spec. It is a superset of CommonMark, and just adds a few extensions. We might have chosen CommonMark as a baseline, except GFM supports tables, which we knew we needed.

The next step was to figure out what to do about features in the MDN source files that weren't supported in GFM. For each feature like this, there are three options:

Stop using the feature: find another way to do the thing we want. For example, we had some markup that would present items in multicolumn layout, and we decided that we could live without this. Making decisions like this helps simplify the MDN authoring experience, which we think is a good thing!
Invent a Markdown-style syntax for the feature. We decided to do this, for example, for <dl> elements, which are very widely used in MDN.
Keep using HTML for the feature. We tried to minimise the amount of HTML we would end up having in our source docs. However, where a feature was localized in use, and where a direct Markdown equivalent did not exist, we decided to keep HTML. We opted to do this, for example, for <sub> and <sup>.

The process for making these decisions was to file GitHub issues presenting the feature, with a few possible options for resolving it, then solicit feedback from writers including Mozilla staff, OWD staff, W3C staff, and members of the wider community. This was the heart of the whole project, and authors care a lot about their authoring tools. So it was important to us that anyone - but especially authors - should be able to participate in the discussion, and that we would not prejudge the outcome. Often the resolution we adopted was not one of the expected options, as people really engaged with the process and helped us make good choices.

After we had a resolution for each issue we updated the documentation for writing Markdown on MDN, and pointed from this document back to the discussion, so people can understand how we reached each decision.

One principle that emerged from this process was: we wanted syntax that would work reasonably well with tools that expected plain GFM. For example, we chose a syntax for notes and warnings that would look OK as GFM. Similarly, we considered using the Kramdown syntax for <dl>, but eventually chose something based on the GFM <ul> syntax, mostly because it would look OK when formatted using Prettier.

Implementing the tools

Once we had a plan for how we wanted the conversion to go, we needed a tool to convert our source files from HTML to Markdown. The conversion tool, h2m, uses the Unified framework, with additions to handle the extra syntax we've defined. It takes as input a directory containing one or more pages in HTML format, and converts any HTML pages it finds into Markdown pages.

We also needed an update to the Yari platform to perform the reverse operation, converting the Markdown back into HTML when we render the pages.

Converting the content

Once we had the h2m conversion tool, we could start preparing the content for conversion. When we run the conversion tool over a set of pages, it also produces a report telling us which HTML features were unconvertible. We could then go through the content, making any changes needed to make the content Markdown-convertible.

Once we were happy with the conversion report, we'd create and review a PR to convert the pages. The conversion was made in two Git commits: one to rename the files from "index.html" to "index.md", and another to replace the file contents. This helps Git understand that we are changing an existing file, so we preserve its change history.

With over 11,000 pages on MDN, this was a big task. First we tested the water with the documentation for the JavaScript Map object. That seemed to go fine, so we followed up with all the JavaScript documentation (about 1000 pages) and then all the CSS documentation (also about 1000 pages). After that we converted the Web API documentation, which was more than 6000 pages, and was a scary PR to merge.

From there we were at about 70% converted, and gradually worked through the rest, finishing up in early October, about 6 months after we started the project.

Building foundations for the future

Looking back from where we are now, we're really happy to be in Markdown. That code sample for <dl> we quoted at the start:

<pre class="brush: html">&lt;dl&gt;
  &lt;dt&gt;Name&lt;/dt&gt;
  &lt;dd&gt;Godzilla&lt;/dd&gt;
  &lt;dt&gt;Born&lt;/dt&gt;
  &lt;dd&gt;1952&lt;/dd&gt;
  &lt;dt&gt;Birthplace&lt;/dt&gt;
  &lt;dd&gt;Japan&lt;/dd&gt;
  &lt;dt&gt;Color&lt;/dt&gt;
  &lt;dd&gt;Green&lt;/dd&gt;
&lt;/dl&gt;
</pre>

now looks like this:

```html
<dl>
  <dt>Name</dt>
  <dd>Godzilla</dd>
  <dt>Born</dt>
  <dd>1952</dd>
  <dt>Birthplace</dt>
  <dd>Japan</dd>
  <dt>Color</dt>
  <dd>Green</dd>
</dl>
```

The code sample quoted above that used to look like this:

<pre class="brush: js"><span class="kd">const</span> <span class="nx">element</span>
<span class="o">=</span> <span class="nx">driver</span><span class="p">.</span>
<span class="nx">findElement</span><span class="p">(</span><span class="nx">By</span>
<span class="p">.</span><span class="nx">id</span><span class="p">(</span>
<span class="s1">'myElementId'</span><span class="p">));</span></pre>

now looks like this:

```js
const element = driver.findElement(By.id('myElementId'));
```

But it's not about individual blocks of content. Overall, writing and reviewing is dramatically easier than it used to be. The beauty of Markdown, to you as a writer, is that it lets you concentrate on expressing concepts and hardly thinking about syntax at all.

At Open Web Docs, we always have to consider which projects to take on next. In particular we have to choose between projects to write new documentation, projects to improve existing documentation, and projects to improve documentation infrastructure. They're all important, but infrastructure projects like Markdown conversion sometimes seem hard to justify because they don't provide an immediate benefit to our readers. The success of the Markdown project was that the rendered pages look (mostly) exactly the same!

But we have to think about the long term. MDN has been around for 17 years, and we hope (and have to work with the belief that) it will be around for decades more. We might have gone on for another year or two with HTML-format documentation, and it would just have been a drag on our productivity. But we knew that this wasn't a sustainable foundation in the long term.

We think we have something now that we could live with for a long time, and we think it's worth the effort it took to build.

Mozilla and Open Web Docs working together on MDN

2022-03-17T00:00:00Z

Mozilla will soon launch MDN Plus, a premium subscription service for MDN readers. Have a look at the Hacks blog post Mozilla and Open Web Docs working together on MDN to read about how Open Web Docs and Mozilla work together, how our missions overlap and how they differ, and how a premium subscription service fits into all this.

_Originally published at https://opencollective.com/open-web-docs/updates/mozilla-and-open-web-docs-working-together-on-mdn._

Vinyl joins Open Web Docs to help maintain compat data

2022-01-24T00:00:00Z

Open Web Docs is thrilled to announce that Queen Vinyl Da.i’gyu-Kazotetsu has joined the team as a contractor to help maintain compatibility data at the BCD project.

Previously a contractor at Google and a long-time BCD community member, Vinyl has a lot of experience with compatibility on the open web. She is the number #1 contributor to the BCD repository!

Web developers expressed frustration with web compat and interoperability and we’re dedicated to help them with accurate data that power both, the MDN compatibility tables and the caniuse.com project.

Please join me in welcoming Vinyl to Open Web Docs!

_Originally published at https://opencollective.com/open-web-docs/updates/vinyl-joins-open-web-docs-to-help-maintain-compat-data._

Join Open Web Docs at Write the Docs Prague Online!

2021-09-23T00:00:00Z

Open Web Docs (OWD) is excited to support the online Write The Docs Prague conference, coming this October 3-5.

OWD team and community members will be attending the talks and participating in the Writing Day. Our goal in sponsoring this event is to learn the latest from and support our fellow documentarians, and to share our knowledge about documenting the Web platform.

Lola Odelola, Developer Advocate at Samsung, has been driving community enablement:

“As part of our community enablement goals for this year, we want to build relationships with the wider writing and developer community. Collaboration has been the driving force behind technical documentation, in particular MDN, and the online writing space is strong because of the numerous writers and developers who contribute to it.”

Samsung Internet and Microsoft are generously underwriting our sponsorship through additional financial support to our Open Collective fund.

We’re also looking forward to working with our partner, Daniel Beck of Mozilla, on the Write the Docs Writing Day where we are facilitating a session about contributing to MDN Web Docs.

We’re looking forward to meeting the WTD community and working on improving the reliability and sustainability of web platform documentation. We hope to see you there!

_Originally published at https://opencollective.com/open-web-docs/updates/join-open-web-docs-at-write-the-docs-prague-online._

Estelle Weyl Joins Open Web Docs Staff

2021-08-19T00:00:00Z

Open Web Docs is thrilled to announce that Estelle Weyl has joined the team this week as a Sr. Technical Writer and Developer Advocate.

A front end engineer with 20-years of CSS, JS and HTML experience, Estelle has always been a web standardista, advocating for a free, accessible, and performant web. Estelle has been documenting and teaching web standards since 2007, writing numerous books, blogs, and tutorials.

She has spoken at over 100 conferences, organized meetups, the Confident Coding series of conferences, and the international web performance conference #PerfMatters. She has written several books including co-authoring CSS: The Definitive Guide, HTML and CSS for the Real World, and authoring Mobile HTML5. She has led CSS, accessibility, JavaScript, and web performance workshops, including teaching with Frontend Masters. She also actively works to improve inclusion in our industry.

At Open Web Docs, Estelle will be focusing on community building in addition to working with the team on improving documentation. We’re excited and proud to have her join the team - please join us in welcoming Estelle Weyl!

_Originally published at https://opencollective.com/open-web-docs/updates/estelle-weyl-joins-open-web-docs-staff._

Jean-Yves Perrier Joins Open Web Docs Staff

2021-08-02T00:00:00Z

Open Web Docs is excited to announce that Jean-Yves Perrier has joined the team today as a full-time Sr. Technical Writer.

Previously a C++ software developer with a 10-year experience in multitasked applications and a long-time advocate of the open web, Jean-Yves has more than a decade of experience on web-related documentation, both as a volunteer and professionally.

In addition to his previous work on MDN and speaking at conferences, he has also been heavily involved with enabling a community of web advocates through the Mozilla Tech Speaker program, organising events, and creating curriculums.

Jean-Yves is thrilled to help us build an Open Web documentation community!

Please join us in welcoming Jean-Yves Perrier!

_Originally published at https://opencollective.com/open-web-docs/updates/jean-yves-perrier-joins-open-web-docs-staff._

JetBrains Joins Open Web Docs

2021-07-27T00:00:00Z

We’re excited to welcome JetBrains to the Open Web Docs Steering Committee!

JetBrains is a software tooling vendor that created IntelliJ IDEA, WebStorm, and many other developer tools.

“More and more people in the JavaScript and web development community are recognizing the importance of good documentation. We at JetBrains recognize it, too. For many years, we’ve equipped our IDEs with MDN documentation, helping developers find information faster and when it’s most relevant.

For us, the OWD initiative is an amazing opportunity to support the open-source community and improve the quality of documents in the tooling used by developers on a daily basis.”

– Piotr Tomiak, WebStorm Senior Software Developer.

With a $20k donation, JetBrains helps us to get closer to our yearly goal to fully fund four full-time Tech Writers to work on Open Web Documentation.

_Originally published at https://opencollective.com/open-web-docs/updates/jetbrains-joins-open-web-docs._

Facebook Joins Open Web Docs as Lead Funder

2021-05-04T00:00:00Z

Open Web Docs is excited to welcome Facebook as a lead funder, joining Google, Microsoft, and Coil on the Governing Committee. As a leading user of, and contributor to, web-based technologies and browsers, Facebook understands how important quality documentation is to the education and productivity of developers.

“Together, Open Web Docs and Facebook will work to ensure developer documentation remains high quality, help drive shared content opportunities with other frameworks, and showcase an even a wider array of browsers that adhere to the MDN-documented technologies,” said Joel Marcey, Developer Advocate and Ecosystem Lead on Facebook’s Open Source Team, and Open Web Docs Governing Committee Member.

In addition to the Governing Committee, Facebook will be joining the Steering Committee, where it will help develop roadmaps and execution to ensure Open Web Docs is working on the highest impact projects for web developers.

“We see the web, both 2D and Immersive, as an important part of the overall XR user and developer experience. In order to better support the XR ecosystem, we are strong proponents of high-quality information for developers targeting browsers on all XR devices. Open Web Docs is a perfect initiative to help drive and showcase these types of underrepresented documentation,” said Dave Hill, Oculus Engineering Manager

Facebook’s sponsorship will contribute to the hiring of full-time Open Web Docs technical writing staff, as well as continue the investment in the future of web platform documentation.

_Originally published at https://opencollective.com/open-web-docs/updates/facebook-joins-open-web-docs-as-lead-funder._

Now Accepting Applications: Open Web Docs Tech Writer / Advocate

2021-04-20T00:00:00Z

Are you passionate about the open web, technical documentation, and growing healthy, sustainable online communities? Join Open Web Docs! We're looking for an experienced technical writer to join Florian, Will, and an amazing community of contributors to help sustain web platform documentation.

This is a full-time, remote position on our small-but-mighty team. You'll work with people across multiple organizations and timezones to improve important web development resources like MDN. The salary for this role is $120,000 USD plus benefits paid in your local currency. Check out the job description below, and reach out to jory @ openwebdocs.org or florian @ openwebdocs.org with questions.

Tech Writer / Advocate - Apply Here

0/ What is Open Web Docs?

The Open Web Docs project is a collective of people and organizations contributing to the betterment of open web platform documentation for the benefit of web developers worldwide. In practice this means contributing to platforms such as MDN Web Docs and others, and taking a lead role on specific content projects within these platforms, in coordination with these platforms as appropriate.

1/ Job Description

Open Web Docs is looking for a Senior team member with both technical writing and developer advocate skills to join our team.

You will both focus on writing projects, tooling and processes related to documentation for Web platform technologies as well as developer advocacy work such as blogging, promotion to the developer community, community management, social media and events.

In particular, you'll be contributing to MDN Web Docs, and related efforts, with an independent editorial voice and championing the needs of the global population of web developers in prioritizing and executing on documentation.

As part of a growing team, you'll engage with the contributor community, the MDN Product Advisory Board, standards bodies, and other partners to propose, plan, and author new content, and maintain and improve existing documentation.

Open Web Docs is an all-remote team. You will work on open source projects and under open licenses, and prioritize inclusion across all concerns.

Together with other OWD team members and the Open Web Docs Steering Committee, you will inform a set of priorities and execute against those priorities alongside other corporate and community partners.

2/ Responsibilities

Contribute to and collaborate with, and continuously improve open Web documentation projects, e.g. MDN
Participate in high-level content & editorial strategy discussions for Open Web Docs involvement in documentation sources
Prioritize documentation work, create roadmap(s), milestones and manage tasks
Improve information architecture standards
Write blog posts, and other engagement with the developer community such as podcasts, interviews and use of social media
Establish and oversee processes that foster healthy communities and productive contributions on our project repositories
Build a vibrant and diverse community around Open Web Docs and MDN.
Provide strategic input on and contribute to key doc infrastructure projects (such as MDN Browser Compat Data)
Communicate with the Web documentation projects Governance Bodies such as the MDN PAB and partners
Contribute to the improvement of team process and style, as well as cross-functional efforts

3/ Job Requirements

Prior experience in technical writing
Great research, planning, writing, editing, information architecture, and content strategy skills.
Experience planning and leading major initiatives, such as the launch of new documentation resources, and large-scale documentation reviews and overhauls.
Experience in remote work and across time zones
Knowledge of open web technologies
Highly organized and able to prioritize and triage various issues and projects
Experience with documentation tooling (git, markdown, “docs-as-code”)
Ability to manage and grow contributions from the community
Technical community management experience
Experience with diversity & inclusion and/or codes of conduct programs within technology communities or open source projects

Apply Now

_Originally published at https://opencollective.com/open-web-docs/updates/now-accepting-applications-open-web-docs-tech-writer-advocate._

Will Bamberg Joins Open Web Docs Staff

2021-02-16T00:00:00Z

Open Web Docs is thrilled to share that Will Bamberg has joined the team today as a full-time Sr. Technical Writer!

Will is an experienced technical writer and brings a great deal of institutional knowledge to the table. He previously worked on MDN at Mozilla, where among other things he wrote and maintained docs for the Firefox Devtools and the Firefox WebExtensions APIs, and led the project to add interactive examples to MDN's reference docs). Will joins OWD from Element, where he's been working on a new website for the Matrix Specification.

At OWD he's interested in helping make web documentation more consistent, coherent, and approachable. Will fills the second position we have budgeted and we are overjoyed to have him aboard. Please join us in welcoming Will Bamberg!

_Originally published at https://opencollective.com/open-web-docs/updates/will-bamberg-joins-open-web-docs-staff._

Community Q&A Session - Join Us!

2021-01-28T00:00:00Z

First and foremost, thank you for the outpouring of support and well-wishes for Open Web Docs following our launch post on Monday. We’re so excited to get to work with all of you to protect and maintain web platform documentation!

To help get things rolling with this new community, we’re hosting our first Open Web Docs community webinar on 17 February at 17:00 UTC (see it in your timezone). We’ll be holding a live Q&A session with Open Web Docs team members, focusing on how we work, our goals, and how you can get involved.

We also want to hear from you - what would you like to see documented, and how would you like to see us make an impact on web platform documentation this year? You can submit your questions or ideas for the panel early via this form (note that responses are visible to the public).

Subscribe to our calendar to receive meeting details directly. We really hope you can make it, but we’ll also record the session so you can watch it later.

We’re planning additional community calls throughout the year. Sign up for our newsletter or follow us on Twitter to get the latest updates from Florian and team!

Special thanks to the W3C for hosting this Zoom webinar.

_Originally published at https://opencollective.com/open-web-docs/updates/community-q-and-a-session-join-us._

Introducing Open Web Docs

2021-01-25T00:00:00Z

High-quality documentation for web platform technologies is a critically important component of our shared, open digital infrastructure.
Today, we’re excited to publicly introduce Open Web Docs, a collective project designed to support a community of technical writers around strategic creation and long-term maintenance of web platform technology documentation that is open and inclusive for all.

Open Web Docs was created to ensure the long-term health of web platform documentation on de facto standard resources like MDN Web Docs, independently of any single vendor or organization. Through full-time staff, community management, and our network of partner organizations, we enable these resources to better maintain and sustain documentation of core web platform technologies. Rather than create new documentation sites, Open Web Docs is committed to improving existing platforms through our contributions.

Florian Scholz joined the project in November 2020 as our Content Lead, working with stakeholders to define initial workstreams. Our 2021 priorities include working with Mozilla’s MDN writers and engineers to support the recent infrastructure transition and to prioritize and move forward with key documentation work, developing a community of contributors around core web technology documentation, browser compatibility data, and improving JavaScript documentation. Additional hires will be announced soon, and those interested can follow our updates at opencollective.com/open-web-docs, https://github.com/openwebdocs and @OpenWebDocs.

Open Web Docs staff are supported by founding sponsors Coil, Google and Microsoft, with additional financial support from Igalia and generous backers on Open Source Collective. Mozilla, Samsung, and W3C provide additional support and participation. Participating orgs are collaborating on content work via weekly editorial and OWD steering committee meetings, and there are plans to create a shared process as we get deeper into the work.

Get Involved

Documentation is for everyone - if you think so too, let’s work together! Check out our high-level goals plan, and let us know what you would like to see prioritized. We’re also planning a live Q&A session the week of Feb. 16 - sign up for our newsletter to get attendance information and receive update digests. And of course, follow @OpenWebDocs on Twitter to get the latest news.

Questions and answers

Q: Is this a new docs platform?

A: No, we are working closely together with existing platforms, and our current priority is contributions to MDN Web Docs.

Q: Is this a competitor/replacement for MDN Web Docs?

A: No. Open Web Docs writers contribute to important developer documentation resources, including MDN. Mozilla is a part of Open Web Docs and a member of its Steering Committee.

Q: Is this the same as Web Platform Docs was?

A: No, Web Platform Docs was a new documentation platform, whereas this is aimed at contributing to existing platforms.

Q: How is Open Web Docs funded?

A: Open Web Docs is funded by contributions from our founding sponsors Coil, Google and Microsoft, and contributors from the wider developer community such as Igalia. We welcome more backers who want to ensure support for long-term maintenance of web platform technology documentation.

Q: How do I get involved?

A: For funding, you can contribute to the project on our Open Source Collective project page. For collaboration opportunities or an interest in becoming a lead funder, please reach out to hello@oscollective.org.

_Originally published at https://opencollective.com/open-web-docs/updates/introducing-open-web-docs._