We met last Wednesday (June 9th, 2021) to go through current OWD project proposals and ideas.
This issue summarizes them so we can discuss which projects to take on in Q3 2021 (the months July, August, September).

Continued projects

These project have been started and it makes sense to continue them in Q3.

• Markdown conversation for more of MDN (CSS docs)
• Finish mixin work (for workers, events, etc.)

Proposed projects

Proposed projects are defined ideas that are clear in scope. They are ready to be worked on.

• WebXR Browser Compatibility
• Fix how MDN distributes Polyfills
• WebView information on MDN
• ARIA roles reference docs
• Modernizing the Learning Area JavaScript modules
• Use webref as the source for CSS formal syntax, instead of mdn/data
• Documenting HTTP/2 and HTTP/3 (discussion)

Ideas

These ideas aren't proposals yet as more details are needed.

• Documenting WebDriver (needs scope, rough outline)
• Web Testing strategies (needs scope, rough outline)
• Fixing MDN page titles (needs decision)
• Fixing how MDN documents dictionaries (needs decision, issue, list of pages affected)

Submit ideas

You can still submit ideas until the end of June and we will take a look!

Looking at 2022 Q2 Projects (Issue #95) I was speculating that MDN could write some intermediate/advanced tutorial or "architecture guide" content which cuts across multiple APIs.

To use Q2 projects as an example, something about implementing themes could combine CSS colors and cascade layers, plus some other APIs (prefers-color-scheme, CSS variables, maybe shadow parts.)

@estelle asked me to file this issue during last week's steering committee meeting. I'm not advocating a massive change of direction here: I really like MDN's comprehensive, individual-method-and-property level API documentation. But advanced material using different APIs together could have compelling value.

Project: Complete the ARIA Roles section

Create Page

• generic mdn/content#12197
• Progressbar mdn/content#12395
• radiogroup mdn/content#12573
• Slider mdn/content#12424

Simple page needed (with link to HTML element)

• ARIA: associationlist role
• ARIA: associationlistitemkey role
• ARIA: associationlistitemvalue role
• ARIA: blockquote role
• ARIA: caption role
• ARIA: code role
• ARIA: deletion role
• ARIA: emphasis role
• ARIA: insertion role
• ARIA: paragraph role
• ARIA: strong role
• ARIA: subscript role
• ARIA: superscript role
• ARIA: time role
  mdn/content#12208

Content needs to be written

• combobox mdn/content#14534
• group mdn/content#12607
• mark mdn/content#12649
• menu mdn/content#12650
• menubar mdn/content#14451
• menuitem mdn/content#14447
• menuitemcheckbox mdn/content#13930
• menuitemradio mdn/content#13996
• scrollbar mdn/content#13245
• searchbox mdn/content#13141
• tablist mdn/content#13088
• tabpanel mdn/content#13743
• tree mdn/content#12979
• treegrid mdn/content#13474
• treeitem mdn/content#13353

Needs updates to links

• button mdn/content#12136
• marquee - mdn/content#12134
• meter mdn/content#12139
• radio - mdn/content#12141
• switch mdn/content#12145
• search mdn/content#12160
• tab mdn/content#12147
• timer mdn/content#12161

Additional Tasks

• All children are presentational in UI roles mdn/content#13164

Browser compatibility data in MDN is usually pretty good but could be better. It is necessary to consult caniuse.com which has links to other sites that describe bugs, edge cases and work-arounds.

Here are some observations of some good points of caniuse. These observations aren't intended as "make MDN like this" or "make BCD like this" but as a starting point to investigate what decisions people use MDN compatibility tables for and how MDN could inform those decisions better:

While there are notes in BCD, examining the content highlights the nature is a bit different. MDN may even have similar content but it is not in context.

The presentation is different, on MDN you have to expand notes per property, per browser; on caniuse the information is in hovercards and you can see a list of "known issues" in one place. There is more consistency between browsers (for example, look at caniuse.com/flexbox notes and see that note 1 applies to 5 browsers from 3 vendors.) The caniuse presentation shows browsers aligned by date, share, current version, etc.; this might be easier to parse for people who have a certain support policy like "two latest versions" or "anything in the past two years" or "x% share" etc.

The granularity of the data are also different; for example, caniuse.com has one entry per browser for "Pointer Events" but on MDN you have to parse a table of 17 rows per browser.

caniuse.com has less friction for reporting data problems than BCD.

The MDN compatibility table may suffer from the simple problem of being at the bottom of the page. caniuse has big #s to encourage deep linking, etc.

This proposes that we work update HTTP documentation on MDN docs to take into account the HTTP/2 & HTTP/3 protocols, a move to Markdown, fix the outstanding issues, and revisions of the unclear areas (CSP, Cache…)

Problem statement

MDN docs articles about HTTP are now several years old. This area overall structure and content are still mostly in good shape and new features that appeared over the years (like Client-Hints for example) were added mostly smoothfully in that structure.

But HTTP has evolved over the years: HTTP/2 is now the most common version in use and HTTP/3 is in the progress of being released. We don't speak about these versions at all and that 1) leave our readers in the vague about these versions 2) makes MDN docs look outdated. We don't need to speak in all details about these protocols – a web dev doesn't need them – but we need at least:

1. An introduction for each of these two protocols;
2. Up-to-date glossaries entries for them, but also related technologies like QUIC;
3. Guide about advanced features and how to use them (Push functionalities?)

Also MDN docs get quite regularly issues about HTTP; there is currently a back-log of 23 issues, about 5% of the overall total, some of them pretty complex to solve.

HTTP docs, like the others area of MDN docs, have to move to Markdown as the devs won't want to keep it in HTML for long. There is a need edit consequently this area of the docs.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Task list

1. Assess in details the HTTP area and make a proposal of new pages to be written, structural to be made.
2. Process with the minor restructuration
3. Add the 5-10 new articles
4. Update the area by resolving the HTTP-related issues on github.
5. Prepare for the Markdown migration (can be done in parallel with the other activities)
6. Migrate to Markdown
7. Review and fix details.

More information

Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.

In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs.
For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/

More information is available at https://openwebdocs.org.
For questions, please reach out to [email protected].

This is a project corresponding to mdn/browser-compat-data#6369 which I and @queengooborg have been working for over a year now. We hope to get to 98% complete by the end of September, and make the push for 100% by the end of the year.

That final push will involve many tricky cases and some compromises, and I think we would really benefit from a shared goal to get it done.

The work can be simplified as ensuring that there are no true or null values in https://github.com/mdn/browser-compat-data/tree/main/api, but the actual strategy is to divide it into categories that can be tackled effectively together, such as event data.

The way that events are documented on MDN and represented in BCD is not great, with different facets of events being treated as separate, and no clear entry point to learn about an event. Previous discussion on this is in mdn/browser-compat-data#7545 and mdn/browser-compat-data#12290.

To summarize the three main facets in terms of BCD entries / MDN pages that often co-exist:

• Event interfaces, such as ClipboardEvent
• *_event entries/pages such as cut_event (in this case there are three more pages)
• on* event handler attributes, such as oncut (these are often on many interfaces, often via the GlobalEventHandlers mixins)

Suggested work:

• Avoiding the duplication between *_event and on* entries and pages, and have a clear main page for each event such as "cut". While element.addEventListener('cut', handler) and element.oncut = handler aren't exactly the same and can have different browser support, I think we should think of this as one feature, which could have partial support.
• Get rid of the last mixins: GlobalEventHandlers and WindowEventHandlers (mdn/browser-compat-data#12290)
• Ensure the correct linkage between events and their interface, so that one can always find the right interface for an event ("cut" → ClipboardEvent and ClipboardEvent → "cut" + "copy" + "paste")

A dark theme for MDN is something that’s been discussed many times, and I think it would be a great feature to add. Out of all discussions on Yari, it’s the most upvoted and most commented discussion (17 upvotes and 40 comments), with seven duplicate issues opened on mdn/yari and four on mdn/content. I have a Userstyle written to add just that, and it’s reached over 750 installs since I put it on userstyles.world on September 28th, 2021. Many users are wanting a dark theme for MDN web docs, and it would be great to get one implemented directly into Yari.

I feel that this is something that will take minimal effort to implement, as the grunt of the work has already been handled in the Userstyle I've written! I'm of course happy to lead this project, and I estimate this should take a week at most to implement.

When web developers are seeking documentation from MDN, the search results often include another site with apparently better SEO but less useful documentation. Developer have to repeat searches to exclude that site or mention MDN.

Something to take the friction out of searching for content on MDN when you don't have MDN open in front of you would help developers get the content they need. SEO, search providers could help.

This proposes that we should start using the w3c's webref project as the source of CSS formal syntax, instead of mdn/data.

Problem statement

In our CSS documentation we have a section "Formal syntax". This is built using a KS macro CSSSyntax, which gets the data from the mdn/data repo.

The specifications are the source of truth for this data, so it's not optimal having this separate copy in mdn/data. Sometimes the version in mdn/data falls behind and we have to remember to update it, or people get outdated information.

It turns out that the w3c already makes this information available in a machine-readable way in their webref project. So this issue proposes that we:

• start using webref as the source for this, rather than mdn/data
• stop maintaining the formal syntax in mdn/data.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Task list

1. Understand the interface of webref and how it maps to mdn/data, and whether there is anything missing that we would need.
2. Get agreement from the dev team to add webref as a Yari dependency.
3. Get agreement from key users of mdn/data to migrate away from it, towards webref probably.
4. Update Yari dependencies to include webref.
5. Update CSSsyntax to use webref instead of mdn/data.

Additional comments

There's a bigger version of this proposal in which we replace not just the formal syntax, but all the CSS data in mdn/data, with webref, and may then be in a position to retire mdn/data entirely. But this is a major step towards that goal, has value in itself and keeps the project small. If, when we get into it, replacing the other CSS data seems straightforward we could consider doing that in this project as well.

Summary: Sidebars are difficult for readers to navigate, but authoring sidebars is sufficiently difficult that making improvements to sidebar navigation is not currently practical. This is a step forward to fixing the latter, so we can fix the former.

Daryl (and others) are working on a visual refresh of MDN. Some of the proposed changes have impacts on information and content architecture. The content and arrangement of MDN’s sidebars are the clearest manifestation of these changes. To minimize unpleasant surprises, there ought to be a specific person representing authors in this process.

@wbamberg has already provided a lot of input in this area, so I think it makes sense that he would be the person to continue this work, but that's not an actual requirement (though it'd be nice to have a single owner, to make definitive judgement calls).

Tasks:

(these are rough tasks—to give a sense of the flavor and size of the work; a lot of this is going to be a consequence of design decisions, which aren't final yet)

• Document requirements for new sidebar structures to meet needs of refresh and authors
• Propose (interim? v1?) sidebar structure and seek feedback from designer, devs, and authors
• Write new static sidebar contents (e.g., write YAML files with actual structures) OR write specifications for new sidebar macro behavior

Stuff that’s not in scope:

• Sidebar implementation (e.g., writing code that generates sidebars)
• General content modeling work (we should do this at some point, there’s more discussions to be done in this area for it to be a coherent project—not ready for execution yet)

This is a write up of a project around specification links that @sideshowbarker and I started to work on and that I'd like to introduce here some more, so that it becomes more transparent why we should do some work on this and what work is involved exactly.

Problem statement

• The specification sections on MDN oftentimes present links to outdated or irrelevant specs. Browser engineers are unhappy to see links non-current specs and web developers get the wrong information about what is the latest standard. Some old specs are redirected by the W3C already, other links just continue to point to dated material or are 404.
• The spec links aren't machine readable like the compat data is. Various tools need a mapping between: mdn url, spec url and compat data.
• The MDN spec sections are inconsistent. If they were rendered from data, like the compat table, we could change the design of this section from a central place and iterate more on it.
• Currently, to add a spec to MDN, one has to add to the specdata kumascript macro in yari to first register a spec. Then it is possible to call a spec macro to display a link. This process is unnecessarily complicated and costs time.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Proposed solutions

• Add a spec_url property to BCD and review all spec_urls for correctness and if they point to the most recent spec version. (See mdn/browser-compat-data#6765)
• Source the MDN "Specification" section from the BCD spec_url. mdn/content#1146
• Improve the rendering of the MDN "Specification" section.

Task list

• Define spec_url for BCD and agree on what sorts of specs qualify as correct and current.
• Populate spec_url for all BCD features (upstream from https://github.com/w3c/browser-compat-data but review data from there)
• Source the Specification section from BCD data
• Remove the specdata macro implementation
• (possibly more here)

https://developer.mozilla.org/en-US/docs/Web/Privacy is a draft and the sub pages are about Firefox. Since these were authored there has been a lot of spec and browser activity to document and consolidate, and the scope of this area continues to grow.

For example many pages on MDN mention fingerprinting, but I don't think there's a page explaining fingerprinting. Understanding a bit about entropy would help developers see the relationship between topics like fingerprinting, navigator.userAgent simplification, and various vendors' conversion tracking proposals, empowering them to productively engage with this important area. Entropy is just one example; another is many privacy-sensitive ad conversion proposals rely on crypto but applied in a way that may be unfamiliar to many web developers.

As well as conceptual material, we need practical material. @sideshowbarker mentioned that:

Stack Overflow is one place where I can say I’ve seen a lot of developer confusion/frustration about [privacy and tracking]. I read a lot of questions on Stack Overflow from developers having issues with cross-origin requests — many of which the developers tag with the cors tag, even though they’re not about CORS; in the minds of a lot of developers, “CORS” just means “cross-origin”. A while back I started seeing a lot of questions about SameSite stuff, so in April I updated the samesite tag guidance, at https://stackoverflow.com/tags/samesite, and re-tagged a few dozen questions with that tag. I notice the tag now has 404 questions — which I think is a lot more than it had at the time I did the re-tagging in April.

On the other hand, @foolip mentioned that:

I don't think different policies around cookies and storage came up much at all in surveys I've looked closely at. In https://insights.developer.mozilla.org/reports/mdn-browser-compatibility-report-2020.html you can search for "the new SameSite setting for cookies that will break some browsers no matter what you do and you have to resort to browser sniffing" so there's something, but not much. Of course that research was long ago in the context of ITP/Potassium.

This project proposes that we work on fixing how MDN distributes Polyfills.

Originally proposed in the MDN discourse https://discourse.mozilla.org/t/mdn-rfc-001-mdn-wiki-pages-shouldnt-be-a-distributor-of-polyfills/24500 but never rolled out, because the MDN wiki didn't really allow to make mass changes. This is now much more approachable with MDN in git.

Problem statement

MDN reference pages often contain large code blocks of Polyfills. This is bad for a few reasons.

• The UX is terrible: The polyfills are distributed in the reference page inside the usual <pre> code blocks which are normally used for static code examples and create a giant blocks of code you normally don’t want to read, but need to copy & paste into your project in order to make use of the polyfill.
• Maintenance is an impossible task: The MDN staff contributors and the core community lacks knowledge and time for of looking after changes to polyfills. Code of polyfills can be really complicated as it implements functions and algorithms described in e.g. the ECMAScript specification or needs to handle weird edge cases. The code aims to be correct and fast, which can be tricky, too. There are bugs filed against MDN polyfills; they remain unresolved.
• Translations outdate, too. I haven’t even looked at how bad polyfills are on outdated wiki translations.
• We do not conform to the advice for polyfill distributors from the W3CTag:
  • We don’t check if we host bad polyfills that are hurting the web. They were in the wiki and editable at any time.
  • We do track spec changes more or less, but we are unable to update the polyfills accordingly.
  • We’re not a CDN for polyfills, we don’t bundle them (someone apparently started doing that for MDN), nor can we guarantee any integrity, or checksums, caching, or anything the like.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Proposed solutions

• We should remove polyfill code blocks from the MDN pages.
• We still want to offer polyfills to MDN readers but we should link to a trusted polyfill source rather than providing untrusted ones inline on the pages.

Task list

• Confirm Polyfill removal and linking to trusted sources is the way forward.
• Figure out trusted sources for Polyfills
• Replace inline Polyfill code with links to trusted Polyfill sources

More information

Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.

In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs.
For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/

More information is available at https://openwebdocs.org.
For questions, please reach out to [email protected].

Just sending off a quick message before I forget: we'd be happy to post announcements from time-to-time. Maybe not everything, but key posts. E.g. after 6-months or something maybe you do a roundup of all the work you've done so far, and then the CTA is "BTW plz donate"

We'll have to work out details but I just want to put it on your radar that web.dev/blog is available to spread the good word

Our HTML documentation contains lots of pages for elements and attributes that have been obsolete for a long time. For example:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/applet
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/basefont
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bgsound
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/big
etc etc
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#deprecated_attributes

Although many of them are still supported in browsers, I don't see any good reason for us to document them on MDN any more. As it is they just get in the way of people looking for things that they should use.

We could list them in a single page under HTML/Obsolete (say), or just delete them (my preference).

This project proposes that Open Web Docs works on adding Temporal docs to MDN.

Repository: https://github.com/tc39/proposal-temporal
Spec: https://tc39.es/proposal-temporal
Docs: https://tc39.es/proposal-temporal/docs/

Problem statement

Temporal is a stage 3 ECMAScript proposal that aims to replace the JS Date API which has many pain points for web developers.

Temporal is a new API with a large surface area: the API reference is a few hundred properties and methods across 10 different types. It is not just a matter of writing a few PRs to get this documented. It likely makes sense to start work on the docs in parallel to implementations so that there won't be a few-month gap between implementation release and MDN docs for it.

See also tc39/proposal-temporal#1449 for the original request for MDN documentation.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Proposed solutions

• Start work on documenting Temporal on MDN. Mark it as unstable for the time being, but make progress together with the implementations, so that docs are in shape when the first implementation is ready.
• Figure out how much is re-usable from https://tc39.es/proposal-temporal/docs/ and give feedback to these docs and the specification when possible.

Task list

A detailed content plan can be worked out as we go. Some first thoughts:

• The reference docs would live under the Standard built-in objects page tree.
  • This means pages for a few hundred properties and methods across 10 different types.
  • This will need compat data and interactive-examples for all reference pages as well.
• Date and DateTimeFormat docs might need some pointers to the new / better Temporal APIs.
• If Date or certain APIs are deprecated or considered legacy now, we should maybe write a guide how to migrate to Temporal (this was proposed in mdn/content#2696) and maybe compare legacy Date APIs and Temporal APIs side by side.
• The JS Guide has a chapter on Numbers and Dates. I guess it makes sense to split this up and have a dedicated chapter just for Date and Time. I reckon some guidance around when to use Date, when Temporal and when the Intl API is needed, too? And there is likely a compatibility story to tell there, too.

Do we need a policy statement from OWD that OWD will only put effort / energy into features & content that is fully free to consume?

WebXR Browser Compatibility

MDN has an essential feature where it provides browser compatibility data for its documented web technologies, including web APIs, JavaScript and HTML. This compatibility is usually represented via a table of browsers, and is essential reading for developers to ensure their apps will be usable across the widest variety of browser platforms.

Currently, the represented browsers in these tables are the common and widely used desktop and mobile browsers. And while this data is of course necessary because of the broad use of these browsers, there are other browser categories that should also be considered when it comes to compatibility.

Virtual and augmented reality (VR and AR, collectively “XR”) devices are becoming more common in households and the industry. These devices have web browsers and WebXR provides the functionality and APIs to the web to those devices. In fact, WebXR is becoming so mainstream that MDN is starting to officially document it.

Proposal

Given the increasing use of XR devices, XR should be added alongside desktop and phones in the compatibility tables on MDN. Mozilla Mixed Reality and Facebook’s Oculus Browser are examples of browsers for XR devices which could appear here. We expect browsers which work on desktops and phones, but support XR features, would continue to appear under their primary modality of desktop/phone.

Each browser vendor would provide the necessary data, in the JSON necessary format, to be added to the compatibility repo. And then that data would be exported into the MDN documentation.

The proposal is as follows:

1. An extra column would be added to the compatibility tables called “XR Devices”, with an icon such as , where native XR-based browsers would be listed.
2. Facebook will work to provide Oculus Browser compatibility data in browser-compat-data. Facebook would like Oculus Browser to appear in the XR Devices column.

Note: Facebook would like feedback on what level of coverage OWD needs to see for (2).

Facebook has noticed some recent XR features are missing from browser-compat-data. Facebook can update missing XR-specific features as it publishes its compatibility data. This will make it easier for other vendors and community contributors to publish updated compatibility data for XR features in other browsers.

About user activation: https://html.spec.whatwg.org/multipage/interaction.html#tracking-user-activation

Web developers might find it useful if there was a page on MDN that lists all the web APIs that can only be called in response to a user action (e.g., a button press). One such API is navigator.share(). There are probably some differences between browsers, so that could be documented as well.

Currently we store information about whether a feature is experimental in two different places:

• in the page itself, as a call to the {{SeeCompatTable}} macro, which adds a banner to the page
• in BCD, as a status flag

We do a pretty good job of maintaining the BCD version, much less well of the version in the page, so they often get out of sync and we get people asking why we are warning people about perfectly good APIs (see e.g. mdn/content#9941, mdn/content#11741, mdn/content#10220, mdn/content#10706, mdn/content#12506, etc etc).

We should display "experimental" banners based on the data in BCD, just as we now display spec tables based on BCD data.

What's involved?

• updating Yari so it displays an "experimental" banner based on BCD
• for pages that don't have BCD (mostly, API overview pages), add front matter to represent experimentalness
• remove the {{SeeCompatTable}} macro

What's the benefit?

Immediate benefits

• more reliable pages
• easier to contribute and maintain MDN, as there's only one place to maintain this

Long-term/strategic benefits

This is in line with our general desire to build MDN content from data, where that's appropriate. We should implement this with an eye to doing something similar for other MDN banners, like "deprecated", "available in workers", "requires a secure context", "requires permissions" etc. All these things should be amenable to maintaining as data and rendering in Yari, rather than being part of unstructured prose content.

Prioritization criteria

Effort

Medium. Need to:

• update Yari to add the banners based on BCD (small)
• update ~960 pages that currently use SeeCompatTable (small)
• design and implement a solution for pages that don't have BCD (small-medium)

Dependencies

Needs a little Yari work.

Community enablement

Make it easier to write MDN docs by only having one place to add the data.

Momentum

n/a

Enabling learners

More reliable docs benefit all users.

Enabling professionals

More reliable docs benefit all users.

Underrepresented topics / ethical web

n/a

Operational necessities

n/a

Addressing needs of the Web industry

n/a

This is a write up of a project around mixin docs on MDN that I've started and that I'd like to introduce here some more, so that it becomes more transparent why we should do some work on this and what work is involved exactly.

Problem statement

What are mixins? Interface mixins in Web IDL are used in specifications to define Web APIs. For web developers, they aren't observable directly, however. They act as helpers to avoid repeating API definitions. This is useful in specifications, but is often confusing in documentation.

• On MDN, web developers are confused when they see mixin docs as they can't instantiate them or do anything with them really.
  • https://stackoverflow.com/questions/43402321/is-settimeout-located-somewhere-besides-window
  • https://stackoverflow.com/questions/56307601/why-fetch-parameter-signal-is-not-documented
• MDN is inconsistent. Sometimes mixins are documented straight from the specs. Almost like they are copied from there. Other times mixins are documented under a real interface, but not under all real interfaces implementing that mixin.
• Mixins are really strange oftentimes. "NonDocumentTypeChildNode" is nothing web developers need to worry about directly.
• ON BCD, we can't really get compat data of a mixin -- only the compat data of real interfaces. Often the compat data is different, for example when things were for a long time on Document already and are now also available with Worker.
  • mdn/browser-compat-data#472 is a long standing BCD issues that presents all the problems with mixins in compat data.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Proposed solutions

1. MDN stops documenting mixins directly.
   • This has been agreed on in mdn/content#1940
2. BCD stops exposing mixin data and exposes data under real interfaces instead.
   • This had been agreed on in mdn/browser-compat-data#8929

Task list

• Agree on how to document mixins on MDN
• Write/Update MDN contribution docs on how to document mixins
• Agree on how to deal with mixins in BCD
• Write/Update BCD data guidelines on how to add mixin compat data
• Update existing MDN pages to avoid mixin pages (detailed tasks see below)
• Update existing BCD files to avoid mixin data (detailed tasks see below)
• Deal with the special cases (large mixins like WindowOrWorkerGlobalScope and friends). Likely come up with exception rules to the guidelines for practicability.

MDN tasks

The following mixin pages need to be updated/removed per the new guideline.

• AbstractWorker
• Body
• ChildNode
• DocumentOrShadowRoot
• GeometryUtils
• GlobalEventHandlers
• HTMLOrForeignElement
• HTMLHyperlinkElementUtils
• LinkStyle
• NavigatorConcurrentHardware
• NavigatorID
• NavigatorLanguage
• NavigatorOnLine
• NavigatorPlugins
• NavigatorStorage
• NonDocumentTypeChildNode
• ParentNode
• SVGAnimatedPoints
• SVGFilterPrimitiveStandardAttributes
• SVGTests
• SVGURIReference
• WindowEventHandlers
• WindowOrWorkerGlobalScope

BCD tasks

The following mixin data needs to be updated/removed per the new guideline.

• AbstractWorker
• Body
• ChildNode
• DocumentOrShadowRoot
• GeometryUtils
• GlobalEventHandlers
• HTMLHyperlinkElementUtils
• LinkStyle
• NavigatorConcurrentHardware
• NavigatorID
• NavigatorLanguage
• NavigatorOnLine
• NavigatorPlugins
• NavigatorStorage
• NonDocumentTypeChildNode
• ParentNode
• SVGAnimatedPoints
• SVGFilterPrimitiveStandardAttributes
• SVGTests
• SVGURIReference
• WindowEventHandlers
• WindowOrWorkerGlobalScope

Coverage of live examples on MDN is spotty, and many are not editable. For example:

https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox is not live
https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids is live but not editable
https://developer.mozilla.org/en-US/docs/Web/CSS/flex-flow live, interactive and editable, although maybe it's not very clear that it is editable (is that what the MDN logo silhouette means?)

If developers could expect to live edit "everything" then they could get more utility out of MDN without the friction of breaking out to jsfiddle, etc.

There have been discussions as part of the Yari transition that the same way BCD has turned to be a very useful source of reusable data, a lot of the pieces of content that constitute an MDN page could also be re-used in other contexts. More generally, moving some of the prose content into more structured data can help with automating and systematizing how MDN pages represent content.

A lot of this structuring has been happening incrementally but it would probably be useful to get a clearer picture of what the goals and constraints would be, possibly recruit consumers of this structured data to make sure that as these incremental improvements land, we're not missing opportunities and creating issues toward that plan.

Summary

Some browser compat data is poorly structured, negatively impacting data consistency, MDN page appearance, and other consumers (e.g., caniuse, VS Code). A relatively small number of changes to BCD and MDN content could eliminate these inconsistencies. Fixing this would involve:

• Moving data in BCD
• Updating pages to use the moved data
• Exploring options for the remaining parts not directly specified (i.e., SVG and webextensions)

Background

Historically, structuring BCD was rather loose. This means some unusual cases exist, which are difficult to communicate to consumers, leave much to be desired in terms of rendering on MDN, and may have more widespread issues (e.g., in caniuse or VS Code). It has also prevented a stronger position on semantic versioning for BCD itself.

See mdn/browser-compat-data#13804 for more details.

Prioritization criteria

• Effort
  • Relatively small, as such things go. I imagine the core part (CSS, HTML, HTTP, and JavaScript) could be completed within a couple of weeks, with a dedicated effort by a writer.
  • The more speculative part is unknown. There's probably a day or two of analysis to be done; completion effort unknown.
• Dependencies
  • None of note.
• Community enablement
  • Not a large effort. It's unlikely to be shared effectively, or lead to more contributions (as this is cleaning up after contributors).
• Momentum
  • This is a new effort, though BCD has substantial reliance factors.
• Enabling learners
  • Not really applicable. Learners are generally unconcerned with compat issues; they need to support their browser, not all browsers.
• Enabling professionals
  • Significant. Developers need reliable information on which browsers support various APIs, CSS properties, etc.
• Underrepresented topics / ethical web
  • Not applicable.
• Operational necessities
  • Not applicable.
• Addressing needs of the Web industry
  • BCD data is widely used on MDN, caniuse, VS Code, and elsewhere. Far reaching in this area.

We met yesterday (September 8th, 2021) to go through current OWD project proposals and ideas.
This issue summarizes them so we can discuss which projects to take on in Q4 2021 (the months October, November, December). For reference, the Q3 issue is #42.

Continued projects

These projects have been started, likely won't get done completely in Q3, and it makes sense to continue them in Q4.

• Markdown conversation for more of MDN. Driver: @wbamberg
  • 70% will be done after the Web/API conversion in Q3
  • Hamish started work on Glossary/ and Learn/. Help him to finish.
  • Finish the rest: HTML, SVG, WebExtensions, MDN/MDN, WebAssembly, and "tiny areas".
  • Tricky one is HTML/ because of HTML :) (and live samples)
• Documenting HTTP/3. Driver: @teoli2003
  • Follow-up from documenting HTTP/2 in Q3
• ARIA roles reference docs. Driver: @estelle

Potential new projects

These are projects that have been discussed before or are new proposals. We will assess them and a stack ranking exercise will determine their importance (every SC member is encouraged to propose projects and to participate in stack ranking). Preparation drivers are people who make sure we have all the information to get started with the project if it gets prioritized by the group.

• Fix how MDN distributes Polyfills Preparation driver: @teoli2003
• WebView information on MDN. Preparation driver: ???
• Modernizing the Learning Area JavaScript modules. Preparation driver: ???
• Use webref as the source for CSS formal syntax, instead of mdn/data. Preparation driver: @wbamberg
  Ideas
• Documenting WebDriver. Preparation driver: ??? (Reeza offered help when it comes to EdgeDriver)
• Web Testing strategies. Preparation driver: ???
• Fixing MDN page titles. Preparation driver: ???
• Updating DOM guides (and completing its reference). Preparation driver: @teoli2003
• Documenting events and representing them in BCD. Preparation driver: @foolip / @Elchi3
• Documenting Performance APIs. Preparation driver: ???
• Improving Privacy Docs. Preparation driver: ???
• WebXR guides. Preparation driver: @dominiccooney / @Elchi3.
• ARIA attributes. Preparation driver: @estelle
• 100% complete BCD API data (no true/null values). Preparation driver: @foolip.
• Sidebars for content architecture refresh. Preparation driver: @ddbeck / Mozilla MDN team.
• OWD project: clean up BCD data guidelines. Preparation driver: @ddbeck

Mozilla MDN projects

Mozilla shared these MDN projects for Q4 and we might want to collaborate with them.

• Content reorg (Ruth)
• Documenting WebGPU (Ruth & Joe Medley)
• Demos (Ruth)
• Project Synth / contribution docs (Ruth)

Summary

The current BCD linter is very limited; it doesn't (and cannot) check several things which impede data quality improvements. Starting a new linter, based on what we've learned from projects such as Stumptown and standalone BCD tests, can bring many benefits to consumers in the form of data quality improvements, such as:

• Consistency up and down the tree (rather than only per source file)
• Consistency across the tree (e.g., checking consistency between HTML attributes and DOM reflected attributes)

With the existing tools, these quality improvements are high risk to achieve.

Moreover, this would have substantial benefits for authors and contributors, reducing friction in contributing new data or making improvements.

Background

BCD's linter is long in the tooth. It grew from a time when we had lower expectations about what compat data would look like and how we'd work with it. With increasing automation and quality, it's no longer meeting our needs.

Unfortunately, its existing design makes it very difficult to change and improve. It has a number of problems, such as tight coupling, redundant code, and extremely limited test coverage. Even simple bugs require substantial excavation to fix; see mdn/browser-compat-data#12673 as an example.

I've written a high-level design doc for a new linter for BCD, which could make use of developments that emerged after BCD's original linter's design cemented, such as our suite of utility functions, Mocha tests, and more.

Prioritization criteria

• Effort
  • This is somewhat flexible. A greater time investment will yield more checks and features; a small MVP that implements one consistency check could be completed in a small number of days.
• Dependencies
  • Needs somebody with familiarity with BCD, Node.js development. Likely Florian or Vinyl.
  • Needs code review. Likely me or Florian, again.
• Community enablement
  • Helps contributors add better data to BCD
  • Not very easy to involve the community in the initial development, however
• Momentum
  • This is a new effort, though BCD has substantial reliance factors
• Enabling learners
  • Not really applicable. Learners are generally unconcerned with compat issues; they need to support their browser, not all browsers.
• Enabling professionals
  • Significant. Developers need reliable information on which browsers support various APIs, CSS properties, etc.
• Underrepresented topics / ethical web
  • Not applicable.
• Operational necessities
  • Not applicable.
• Addressing needs of the Web industry
  • BCD data is widely used on MDN, caniuse, VS Code, and elsewhere. Far reaching in this area.

Summary: To maintain the high quality of BCD data (which appears in compat tables and caniuse), we have conventions for recording certain data. Some of those conventions have been recently established, but were never written down, leading to a risk that that data will not be maintained properly. This proposal addresses that risk.

Recent efforts have caused BCD's data guidelines to slip out of sync with our actual practices. I'd like to propose a (hopefully small) effort to bring the data guidelines back in sync.

Some of these tasks have been nominally claimed by people who participated in them (e.g., sideshowbarker for spec_urls and foolip for globals). Perhaps they still want to work on them and might benefit from having a designated reviewer, or perhaps they'd like to hand off the task to some else.

I'd also be willing to be a reviewer, to support any or all of this work.

Tasks:

• Write (or review) a data guideline for how to choose a spec URL (e.g., which spec and URL fragment) (i.e., document the completed spec URL work
• Write (or review) a data guideline for how to record globals (e.g., when to put an API in __globals) (i.e., document mdn/browser-compat-data#11518)
• Improve navigation of data guidelines (e.g., add more headings to group related guidelines and put the guidelines into some sort of meaningful order)

Problem statement

Our documentation of the DOM is really old. Most of the guides have been written around 2005 at a time DOM implementations were not really portable between browsers.

Given that:

• DOM is at the core of the Web, and any beginner must understand it,
• our docs is not coherent, having been edited bit by bit over the years when something has been added/removed,
• have good SEO (2 MDN pages came first when I tried "DOM" in Google Search) ,
• there is almost no information about the DOM in the Learning Area of MDN (DOM in the Learning Area)

we should update this area.

Note that we can split this into different parts, not all necessary to be done at once:

• the guides are pretty outdated and are likely to be completely revised (about 10 pages)

There are other guides to consider, like the Using shadow DOM guide in the Web components area.

• the reference pages can be numerous and we should analyse them more in detail before committing. (How many pages, how many are missing, …)
• Things like XPath and XSLTProcessor that are in the DOM spec should be left untouched.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Task lists

TBD

This project proposes that we work on enhancing MDN syntax boxes in MDN JavaScript and Web API docs.

Originally proposed a few years ago on the MDN mailing list https://groups.google.com/g/mozilla.dev.mdc/c/eS12O5mAI-A/m/J1Qd-HajBgAJ and recently re-proposed on mdn/content: mdn/content#2202

Some work in this direction has happened, but it has only been tested on a few pages and not rolled out widely enough. Also, talking to actual beginners, and doing user research and A/B tests would help to further enhance this section.

Problem statement

The syntax section on MDN helps readers to quickly get to the gist of what an API's method or constructor does. Often, the snippets in the syntax section are copy-pasted. Readers might know what splice does, but they don't always know the parameters, for example.

Currently, syntax sections are often using the more complex BNF notation. For example, array.splice(start[, deleteCount[, item1[, item2[, ...]]]]) confuses readers.

Also "[]" is an array in JS, so a method like arr.sort([compareFunction]) can look confusing.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Proposed solutions

• As a first step, we should eliminate confusions that come with BNF notations. The proposal that is most promising seems to be to switch to multiple lines. We should roll this out to a sensible amount of docs and check if works better and avoids the confusions readers currently face.
• At a later step, we can think about how to make these sections even better. For example, an idea by Hamish Willee is to also add types to the syntax. This would probably address a need the TypeScript community has. More research is needed to confirm this, though.
• Ideally, we work with users and/or A/B tests. This adds a dependency though. So, we will probably roll out the multi-line version and see how people react to it to confirm the approach.

Task list

• Agree on a way forward to avoid the BNF syntax. Done! We're going with multiple lines for now.
• Update MDN contribution docs. Done by Hamish Willee!
• Update MDN JS docs

Follow ups:

• Update MDN API docs
• Do more research around adding types

Ideally Web APIs should be categorised. This will benefit visibility for users, but also help drive how we organise the standalone demos MDN has. Currently the majority of 'github' demos within the MDN org are Web API ones and they could do with an update & better architecture. However this proposal is the first part to categorisation, which is to start by moving interface docs under their relevant Web API.

For example:

• Web Audio API (Parent folder)
  • AudioNode (Interface)
    • context
    • numberofinputs
    • ...
    • connect()
    • disconnect()

There's a couple of caveats - some things just don't fit in this structure (like fetch) and possibly can be left out. Also probably worth a discussion is tutorial docs, which are usually under the main API folder.

One possible solution is:

• Web Audio API (Parent folder)
  • Interfaces
  • Tutorials

It might be worth considering tutorials which cover more than one API - should these be a part of learn?

Effort

This should be just the first step to categorising Web APIs. However there would be a lot of moving of docs, so it's not a small effort

Dependancies

No changes to the platform should be needed

Community

One approach could be to raise an issue for each API detailing which docs need to be moved. This might encourage community help

Momentum

There's another proposal to create a searchable page for APIs. This is really the platform grounding to begin something like that

Enabling learners

Eventually a better way to discover APIs - however this is not covered by this first part

Enabling professionals

As above

Underrepresented topics / ethical web

N/A

Operational necessities

N/A

Addressing needs of the Web industry

Eventually be able to categorise Web APIs and mirror that with the external examples we have. Thus making it easier for users to discover both the docs & code examples.

This was originally filed by Chris in mdn/content. Although the project is now complete I wanted to keep a record of the original proposal for traceability.

This RFC proposes that we work on modernizing the Learning Area JavaScript modules
available on MDN.

Problem statement

The JavaScript learning area modules are pretty good as they stand, and still
helpful to aspiring web developers. The main problem is that many of the
component articles were written before the time that MDN's JS policy was
changed (from "don't use ES6 features, they are too modern" to "use modern
features").

As a result, a number of articles are a bit out of date, or teach the old way
of doing something first, with the new way added in as a new section at the end.

Examples:

• In the Handling text — strings in JavaScript
  article, old-school string concatenation is introduced centrally,
  whereas template literals are introduced at the end as a newer syntax that
  you'll also come across. This should really be done the other way round.
• In the arrays introduction,
  the basics are explained just fine, but there is no coverage of modern array
  methods that are very commonplace in JS these days, such as map() or filter().
• In the JS objects module,
  old-school constructors and prototypes are introduced first, and ES class
  syntax is tacked on the end as an afterthought. This should be the other way
  round.
• We did some work on making sure that const/let is used in appropriate
  Places instead of var. We should check to see if there is any more work to
  do here.
• We should include a guide early on about targeting browsers, where we could
  cover things like considering which browsers/non-browser runtimes you need to
  support, making it clear that we only support modern browsers in these guides,
  and setting up tools like Babel.js if you want to support ancient engines.

Priority assessment

This list checks this project against the OWD prioritization criteria.

• Effort: Medium/High: There are over 40 JavaScript articles in the
  learning area, and each one needs to be audited, a decision made about what we
  should do with it, and then rewriting work done. Related examples also need
  to be updated.
• Dependencies: Not much to mention here.
• Community enablement: Yes. Each page rewrite is a self-contained task, so
  we could get community to help out here.
• Momentum: Medium. A lot of features we'd be writing about are pretty
  stable, but the technology is very popular.
• Enabling learners: Yes!!
• Enabling professionals: Yes, somewhat. Even professional web developers
  can often benefit greatly from an authoritative source of information show
  the modern way to write JS. We should aim to keep this pretty up-to-date.
• Underrepresented topics / Ethical web: n/a
• Operational necessities: n/a
• Addressing the needs of the web industry: n/a

Proposed solutions

Audit existing articles, work out how to update them, get them rewritten.

Task list

• Agree on an overall strategy for the updates. For example, is there a
  particular set of ECMAScript that we want to stick to documenting in this
  resource? How new is too new? Do we gate it on what is supported in at least
  two rendering engines, or some such thing? How do we deal with
  backwards-compatibility? Show examples of how to support older browsers, or
  just teach everyone how to use Babel.js to begin with?
• Audit each page. For each one, write a list of what needs to be done to get
  that page updated in line with the above strategy.
• Find writers to help do this work.
• Divide the writing and reviewing work up between the available writers.

All the roles were documented in Q3 2021 with the exception of the widget roles.
This project would make the ARIA roles section of the MDN complete.
Roles to edit include:

Full documentation for:

• scrollbar - https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role
• searchbox https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role
• separator (when focusable) https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role
• slider https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role
• spinbutton https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role
• switch https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role
• tab https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role
• tabpanel https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role
• treeitem https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role
• combobox https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role
• menu https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role
• menubar https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role
• tablist https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role
• tree - https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role
• treegrid https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role

Documentation for some of these exist. Others don't. But all need improvement.

Brief documentation needed for:

• button https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role
• checkbox https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role
• gridcell https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role
• link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/link_role
• menuitem https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role
• menuitemcheckbox https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role
• menuitemradio https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role
• option https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/option_role
• progressbar https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role
• radio https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role
• textbox https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role
• grid https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role
• listbox https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role
• radiogroup https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role

The reason the latter section needs brief pages is that the roles exist, but should not be used. So, we need to include them for completeness, but we don't need lots of details, just an explanation of existence and purpose, and a "do not use" warning.

Cascade layers are part of Interop 2022

Cascade layers give web developers more control over the cascade. They provide a way to group selectors into layers, each with its own specificity. Cascade layers are now supported in most, but not all, browsers.

Cascade layers mean developers don't need to order selectors carefully or create highly specific selectors to overwrite base CSS rules. It also means there has been a change to the cascade.

We have to:

• Create a Cascade layers tutorial (new)
• Rewrite Introducing the CSS Cascade to include Cascade layers
• Rewrite Cascade and inheritance
  • Live example on layers for tutorial
• Rewrite CSS Cascade Skills test
• [-] Add @layers to CSS Custom Properties for Cascading Variables
• Rewrite specificity
  • include @layers impact on cascade
  • including proximity of elements
  • explain specificity algorithm
• Document !important

[This message has been edited by various OWD members]

We have assessed different projects (and added new ones). Here is the list of projects we think are the most valuable for Q2, as well as the list of other projects considered.

( ❌ = not started, ⏳ = in progress, ✅ = completed)

Q2 projects

• Revamp our CSS color documentation @teoli2003 ⏳(rolling over to Q3)
• Page Types @wbamberg ⏳
• Project: ARIA widget roles @estelle ✅
• Branding: Open Web Docs Website @wbamberg, @Elchi3, @estelle @queengooborg, @lolaodelola ⏳
  • OWD Logo @estelle, @queengooborg, @lolaodelola ⏳
• CSS Cascade Layers @estelle ⏳
• Performance docs @Elchi3 ❌
• BCD @queengooborg
  • Converting BCD to ESM ✅
  • Converting BCD to TypeScript ✅
  • Regularize feature namespaces for CSS, HTML, HTTP, and JavaScript ❌ (rolling over to Q3)
  • Adding build-time mirroring ✅
  • Convert pre-mirrored statements to build-time mirroring ✅
  • Implementing BCD's next-gen linter ✅
  • Demix GlobalEventHandlers and update events ⏳(rolling over to Q3)

Other projects considered

• Fix how MDN distributes Polyfills @teoli2003
• WebView information on MDN (removed in mdn/content#13768)
• Fixing MDN page titles
• Documenting Performance APIs
• Improving Privacy Docs
• Clean up BCD data guidelines @queengooborg
• WebXR guides @dominiccooney / @Elchi3
• Web Testing strategies [Needs better definition]
• Sidebars for content architecture refresh @ddbeck
• Missing HTML attributes @estelle
• Organise Web APIs

2022 Q1 completed projects

These projects were completed in Q1.

Summary

Update our pretty old documentation about CSS colors by rewriting <color> and writing a few guides and glossary entries to describe modern concepts like gamut and color schemes.

Background

Our documentation about CSS color is pretty old. Its structure dates from a time when keywords and rgb() were the only possible CSS Colors.

Nowadays, numerous new color schemes have been added, and are listed on the page but without overall explanations. CSS Color Level 5 is adding two more functions color-mix() and color-contrast() that are documented but not linked from <color>. They are implemented behind flags by two browsers and CSS Color Level 5 is part of INTEROP 2022.

New concepts in the world of web development (like gamut and color schemes) are not explained on MDN but only linked to Wikipedia where the explanation is larger than the one needed in web development.

Prioritization criteria

• Effort
  • Small to medium. This is the update/creation of 5 to 10 pages, with some research.
• Dependencies
  • None.
• Community enablement
  • Not really.
• Momentum
  • This will support INTEROP 2022.
• Enabling learners
  • Currently the <color> documentation is complex this will help untangle basic and advanced concepts, as well as having a guide and explanation for the advanced ones.
• Enabling professionals
  • Significant. This is a new development of the web.
• Underrepresented topics / ethical web
  • Not applicable.
• Operational necessities
  • None.
• Addressing needs of the Web industry
  • INTEROP 2022.

Websites are the center of an organization's online presence. The site serves as the organization's online hub of information. openwebdocs.org is where visitors should go for information about our projects, where search engines direct visitors, including volunteers and potential contributors, where email announcements should lead to, and a hub for links in social media posts. Instead, we have MDN, a GitHub repo, Google Docs, and a page (and our current redirect) https://opencollective.com/open-web-docs

Creating an OWD website will have the following benefits:

1. Makes us appear legitimate
2. Informs visitors how to reach us
3. Informs potential volunteers how to get involved
4. Converts donors: Convinces (and enables) potential financial donors to contribute
5. Tells our story
6. Expands our reach
7. Drives new Interest
8. Provides for a positive impression
9. Provides a central repository to links to our projects, issues, newsletters, etc.

In general, the website will help boost all our efforts

What is a page type?

A page type is a concise, human-readable term that identifies the type of web platform feature that an MDN page is about. For example, it might identify that a particular page documents a CSS property, or a JS method, or an HTML element.

Why page types are important

It's important for reference docs to be consistent, so they contain the same kind of information, organized in the same kind of way. For example, it's important that every CSS property page includes a browser compatibility table and that it appears in the same spot on every page, under the same title. Different types of page should include different elements: for example, a JS class page should have a link to the page describing its constructor, and a CSS shorthand property should contain a list of the properties it sets.

To be able to make rules like this, we need the concept of page types. And of course we use this concept all the time: whenever we say something like "this page ought to have a Syntax section" we are implicitly leaning on page types.

Also, any time want to present a collection of docs in an organized and navigable way - as in the sidebar for a JS global object, for example, where we want to have separate lists for properties, static methods, and instance methods - we're leaning on the concept of page types.

So we already have page types. What we are missing is a sharp and consistent way to define them.

How we represent page types at the moment

On MDN we currently use a few different hints to represent the type of thing a page documents, but the most common one is the page tag. The main problem with using tags for this is that they don't have any semantics. So if we define a tag like "CSS property" it's not at all obvious why this should not apply to, say, a landing page listing all CSS properties (and in fact this kind of blurring of the meaning of tags happens all the time). It would be a lot clearer to have a dedicated front matter key for this with its own definition. See also: mdn/content#3424 (comment).

We also describe page type templates in the MDN contribution docs: https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types. But these are incomplete and don't correspond to any identifier in the page - so they don't offer a way to map from a template to a particular page.

What a page type could look like

In this proposal the page type is a new front matter key called "page-type" whose value is a single string. Its possible values could be something like:

javascript-class
javascript-constructor
javascript-method
javascript-property
css-at-rule
css-data-type
css-function
css-property

...and so on

What we would use page types for

Sidebars

At the moment MDN pages call a macro to create the sidebar. So CSS pages include {{CSSRef}} at the top, for example. If pages instead of a page-type, and that can determine the sidebar to use, we don't need authors to make these macro calls any more: the correct sidebar can automatically be chosen by Yari.

Note that this won't work for all cases. In particular guide pages and landing pages don't map to a sidebar (because there can be JS, guides, or CSS guides, ...), so even if we do want to define "guide" and "landing-page" types (which is not certain) they would not be enough to determine the sidebar. However, this is a small minority of cases (probably less than 10%).

Tags

As noted above, we use tags as page types for building sidebars. We could replace all these references with references to page types instead.

Linting against a specification

More interestingly, given a reliable way to identify the page type, we could define a specification for pages of given type. The specification could list the set of elements that a page of that type must or may to contain. We can then test our pages against that specification, and know that our pages are consistent (or, where they are not). For example, we could have a list of pages that don't have a BCD table, but should.

Building pages to a specification

With linting, people write pages and we use the specification to check that they have a valid structure. The inverse of that is where people provide components of documentation, and a specification for a page, and the system builds complete pages. This is better than linting in some ways because authors don't have to understand the structure and don't have the chance to get it wrong.

We already do this to some extent using things like BCD, mdn/data, and interactive examples as components of a page, but we could take it a lot further. Why do authors have to remember the position on the page where the BCD table or the interactive example live?

We might start by linting pages, then eventually move towards building pages. Or we might build parts of pages, and lint the rest, and gradually build more and more pieces.

What's the actual project?

The current proposal is:

• define a complete set of page types for MDN's reference pages
• document the types in our meta-docs
• add a front matter items to every reference page representing its type

In practice we would do this in sections - JS, CSS, Web/API, and so on.

See also

• https://github.com/mdn/content/discussions/5162

Prioritization criteria

Effort

Large? Need to:

• define page types for all reference pages
• add them to all the pages

In practice the initial project might target a subset of the docs.

Dependencies

None.

Community enablement

Eventually, this would make it easier to contribute docs successfully, by making it clearer what's needed in a page.

Momentum

n/a

Enabling learners

More reliable docs benefit all users.

Enabling professionals

More reliable docs benefit all users.

Underrepresented topics / ethical web

n/a

Operational necessities

n/a

Addressing needs of the Web industry

n/a

Create a new logo.
Determine the marketing (not writing) voice

This issue proposing adding a Web Monetization meta tag to MDN to enable OWD to seamlessly accept micropayments/donations from Web Monetized users.

Users visiting MDN already have a subscription from a Web Monetization provider and do not have to pay additional fees to support MDN when they use the docs.

Problem Statement

MDN is visited by many users who already have a subscription from a Web Monetization provider. However, even though they do not need to take any other action, OWD is currently not taking micropayments/donations from the users visiting the site.

The impact of this is that we are losing $0.36/hour (as of today) for every hour a Web Monetized user visits MDN. This donation could go towards covering some OWD costs or be donated to organizations like Creative Commons, Web Foundation, or Contract for the Web since they already have an Interledger Payment pointer.

Considering the potential impact for the community vs the effort, 1 line of code (<meta name="monetization" content="$your.payment.pointer.address/xxx">), it will likely be useful to the community that we add the meta tag.

Priority Assessment

This table checks this project against the OWD prioritization criteria.

Implementation Process

• Decide which Interledger payment pointer to use
  • Get a Payment pointer for OWD so OWD receives the payment
  • Use the payment pointer of a Non-profit payment pointers
• Add the meta tag to the of the pages

Resources

• Web Monetization Spec
• Web Monetized sites

A small group of engineers spent about 30 minutes reviewing existing Performance API and Performance Timeline documentation to search for any opportunities for improvement.

We found many examples of improvement opportunities:

For example:

• Lack of a general "Performance Guide"
  • Perhaps can borrow from the explainer with some updates?
  • Perf APIs primer should perhaps be turned into an MDN page.
• Issues in references pages:
  • e.g., In PerformanceObserver reference the description for observe() method does not match the descriptions from the actual observe() method reference page. Both descriptions could use updates.
  • e.g., LCP, ElementTiming, and others do not describe the inherited attributes from PerformanceEntry even though their semantic meaning is specific to the API in question.
  • e.g. PerformanceLongTaskTiming reference is basically empty.
• Issues with Examples throughout reference pages.
  • e.g., dictionary options passed to PerformanceObserver.observe() use entryTypes instead of type and buffered.
• Certain APIs are labeled experimental when they should no longer be (example PerformanceObserver)
• Some new experimental apis are not documented, while some long abandoned apis are still documented (e.g. Frame Timing).
• Various "see also" links are out of date (example)

We think improvements in this area would be very valuable, and greatly appreciated!

#66 and similar efforts in the past have eliminated all true and null values in BCD for API, CSS and JS data. @queengooborg and I used https://mdn-bcd-collector.gooborg.com/ to finish the API data over the course of 2021, and the collector also covers a lot of CSS and JS.

We have found that comparing BCD to feature detection results invariably finds a lot of errors in BCD. By comparing BCD with the collector results, we can find many false positives and false negatives. This will likely lead to many features looking "better" (more green) as support has shipped in the past 2 years but BCD was never updated.

Such cross-checking can in principle go back over 10 years, but I suggest limiting it to browser releases after 2020-01-01, and updating earlier data only when it's really easy and does not require much digging to verify.

For reviewers, here's a link to the guide on how to review collector PRs: https://github.com/GooborgStudios/mdn-bcd-collector#reviewing-bcd-changes

Hey, I'd like to offer my help. Please let me know how can I contribute.

cc @robnyman @kypflug

This proposes that we work on migrating MDN to use (GitHub-Flavored) Markdown instead of raw HTML for the authoring format.

Note that this is a joint project with the Mozilla MDN engineering team. We will need to work out how to divide responsibilities between OWD and MDN engineering so we can work together well. Note also that Mozilla are very likely to do this project anyway, with or without OWD involvement. However, OWD have a lot of:

• knowledge of MDN content and the problems it might pose for a Markdown conversion
• experience thinking through these problems
• opinions about the direction MDN's authoring format should take.

Problem statement

Before Yari, MDN docs were edited in a WYSIWYG editor, with an option to edit the page as raw HTML.

Since Yari, it's only possible to edit MDN docs as raw HTML in a text editor.

This is slower, more difficult and results in more formatting errors. It also results in worse documentation because authors have to think about the formatting all the time instead of the concepts they want to express. People who aren't familiar with HTML may not be able to contribute at all.

It's also harder to review.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Proposed solutions

In this project we would migrate a single subset of MDN docs to Markdown.
It would make sense for this to be a coherent part of the site, big enough to
discover the problems we're most likely to encounter, but small enough to be manageable. For example:

• all the JS docs: about 1000 pages, or 1/10 of all the en-US Web docs
• all the CSS docs: about 1000 pages, and probably more challenging than the JS docs

Then at the end of this project we would have:

• content for that section in Markdown in mdn/content
• documentation for authors, focusing especially on any customizations we have implemented
• extra tooling in Yari to convert this content into HTML

After this project we would convert the rest of MDN, section by section.

Task list

1. Analyze features of MDN content that are likely to make a straight Markdown conversion problematic, and design custom solutions to them. Solutions could include things like:
   • extending basic Markdown syntax to support them
   • writing new KumaScript macros so we can make them build parts of the page
   • documenting exceptions where authors must use raw HTML
2. Implement HTML->Markdown conversion that includes these customizations
3. Where content changes are needed, update the content
4. Implement Markdown->HTML conversion in Yari that reverses these customizations
5. Verify the rendered pages, and implement any extra customizations as needed.

SVGs are common place and there's a few parts of the docs which highlight the time is which these docs were first written. There's a lot of good stuff, but re-considering page structure and removing unnecessary docs would be good.

• Reconsider element & attribute page data structure - element pages list all global attributes - do they need to? https://developer.mozilla.org/en-US/docs/Web/SVG/Element/circle
• Tutorials need more exposure - also this page either needs more or other sections to be removed https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial (I would personally love to see some SVG filter tutorials)
• Other pages also don't have a lot of exposure/x-linking https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/Presentation
• Lots of references to SVG 1.1 - should possibly update these to 2
• Lots of things removed https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model#svg_interfaces and depreciated https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ascent
• Some things now irrelevant: https://developer.mozilla.org/en-US/docs/Web/SVG/Server-configuration

Is there a way to better marry presentational attributes with CSS properties?

Effort

There's quite a few things to address, so probably a large effort. However the SVG docs are pretty complete.

Dependancies

No changes to the platform should be needed

Community

Not sure if there's much engagement to be had

Momentum

My concern is it's a catch 22 - there's some good stuff in the SVG docs which is possibly going un-noticed

Enabling learners

Would be good to refresh the tutorials and make them more discoverable

Enabling professionals

A more structured approach to the ref docs would help

Underrepresented topics / ethical web

N/A

Operational necessities

N/A

Addressing needs of the Web industry

Making SVG docs better for everyone 💅

After or in parallel with #85, we should create a process for BCD maintenance.

In short, the process here would be to test each new beta and stable browser release with http://mdn-bcd-collector.appspot.com/ and updating BCD to be consistent with the results, on an ongoing basis.

@queengooborg WDYT?

We will be meeting next week (January 14, 2022) to go through current OWD project proposals and ideas.
This issue summarizes them so we can discuss which projects to take on in Q1 2022 (the months January, February, March). For reference, the Q4 2021 issues is #55 and Q3 was #42.

Continued projects

These projects were started, but not completed in Q4. It makes sense to continue them in Q1.

Completed

For reference, the following projects were completed:

Potential new projects

These are projects that have been discussed before or are new proposals. We will assess them and a stack ranking exercise will determine their importance (every SC member is encouraged to propose projects and to participate in stack ranking). Preparation drivers are people who make sure we have all the information to get started with the project if it gets prioritized by the group.

Continued Projects

• Updating DOM guides (and completing its reference) @teoli2003
• Modernizing the Learning Area JavaScript modules
• Documenting events and representing them in BCD @foolip / @Elchi3
• 100% complete BCD API data (no true/null values) @foolip & @queengooborg

Projects for consideration

• Fix how MDN distributes Polyfills @teoli2003
• WebView information on MDN
• Fixing MDN page titles
• Documenting Performance APIs
• Improving Privacy Docs
• Clean up BCD data guidelines @ddbeck
• WebXR guides @dominiccooney / @Elchi3
• Web Testing strategies [Needs better definition]
• Sidebars for content architecture refresh @ddbeck
• OWD Logo
• Branding: Open Web Docs Website @estelle
• Missing HTML attributes @estelle
• Project: ARIA widget roles @estelle
• Organise Web APIs
• SVG docs need some love

Mozilla MDN projects

Mozilla shared these MDN projects for Q4 and we might want to collaborate with them.

@Rumyra / @ddbeck Please complete this section with what has been done and what is going to be done.

• Content reorg (@ddbeck)
• Documenting WebGPU (Ruth & Joe Medley)
• Demos (Ruth)
• Project Synth / contribution docs (Ruth)

As a prerequesite for completing issue #24, a quaterly goal of OWD, we need to have the browser-compat clause in the front-runner of any relevant page of MDN.

I have a Python script helping me, but we are speaking about updating 6000+ pages of MDN. I will break this down into small(ish), and manageable, PRs.

Here I will track progress:

• api/a* – PR mdn/content#5400 – 215 files
• api/b* – PR mdn/content#5401 – 186 files
• api/c* – PR mdn/content#5404 – 418 files
• api/d* – PR mdn/content#5406 – 343 files
• api/e* – PR mdn/content#5407 – 265 files
• api/f* – PR mdn/content#5409 – 144 files
• api/g* – PR mdn/content#5410 – 135 files
• api/h* – PR mdn/content#5411 – 426 files
• api/i* – PR mdn/content#5412 – 173 files
• api/[jkl]* – PR mdn/content#5413 – 69 files
• api/m* – PR mdn/content#5415 – 334 files
• api/n* – PR mdn/content#5418 – 177 files
• api/[opq]* – PR mdn/content#5536 – 414 files
• api/r* – PR mdn/content#5423 – 483 files
• api/s* – PR mdn/content#5426 – 536 files
• api/t* – PR mdn/content#5427 – 154 files
• api/u* – PR mdn/content#5428 – 99 files
• api/v* – PR mdn/content#5441 – 120 files
• api/w* – PR mdn/content#5444 – 504 files
• api/[xyz]* – PR mdn/content#5447 – 203 files

Subtotal: standard api: 5398 files

• api/[abc]* (unusual) – PR mdn/content#5551 – 10 files
• api/[d-q]* (unusual) – PR mdn/content#5568 – 10 files (and follow-up PR mdn/content#5598 )
• api/[r-z]* (unusual) – PR mdn/content#5586 – 30 files
• css/* – No PR (already done) – 0 file
• html/Elements/input/* – No PR (already done) – 0 file (Done by @Elchi3 in mdn/content#5166)
• html/Elements/* – PR mdn/content#5471 – 132 files
• html/Elements (unusual) – PR mdn/content#5502 – 4 files
• html/Global_attributes/* – No PR (already done) – 0 file (Done by @Elchi3 in mdn/content#5149)
• manifest/* – No PR (already done) – 0 file (Done by @Elchi3 in mdn/content#5164)
• http/headers/CSP – PR mdn/content#5468 – 32 files
• http/headers/* – PR mdn/content#5469 – 124 files
• http/status/* – PR mdn/content#5470 – 30 files
• http/methods/* (and data_URL) – PR mdn/content#5472 – 10 files
• http/* (unusual) – PR mdn/content#5538 – 2 files
• javascript/* – No PR (already done) – 0 file (Done by @Elchi3; see mdn/content#4726 and mdn/content#4594)
• mathml/* – PR mdn/content#5494 – 29 files
• svg/* – PR mdn/content#5496 – 277 files
• xpath/* & xslt/* – PR mdn/content#5500 – 3 files
• mozilla/add-ons/webextensions/api/* – PR mdn/content#5476 – 400 files
• mozilla/add-ons/webextensions/manifest.json/* – PR mdn/content#5492 – 34 files
• mozilla/add-ons/webextensions/* (unusual) – PR mdn/content#5504 – 131 files
• webdriver – PR mdn/content#5592 – 11 files
• missing bcd in api/* – PR mdn/content#5630 – 8 files

Special cleaning PR

• Remove duplicate RTCPeerConnection_idpvalidationerror_event PR mdn/content#5570
• Merge OffscreenCanvas.toBlob into OffscreenCanvas.convertToBlob PR mdn/content#5590
• Merge XMLHttpRequestresponsetype into XMLHttpRequest.ResponseType PR mdn/content#5664
• Merge ServiceWorkerState into ServiceWorker.state PR mdn/content#5660
• Merge AudioContextLatencyCategory into AudioContextOptions.latencyHint

Update documentation about it:

• Update BCD documentation
• Update Page templates – PR mdn/content#5544 – 12 files
• [Partial duplicate of mdn/content#5225; be sure to integrate discussed points]

We should have complete documentation for the ARIA spec within MDN.

ARIA roles is currently in development.

There are 50+ aria states and properties needing to be documented.

1. Index page at /en-US/docs/Web/accessibility/aria/attributes
   • Four groupings: widget, live region, drag-and-drop, and relationship attributes
   • quick links to all the attributes based on group (name only)
   • List of all the attributes in alphabetical order with summary
   • include link to the role attribute, which doesn't start with aria-*
2. 53 New documents: one for each of the widget, live region, drag-and-drop, and relationship attributes

As we receive invitations and/or want to participate at online or in-person tech events, we should add a statement about D&I to this repo.

It can be very similar to Samsung Internet's statement https://developer.samsung.com/internet/diversity-inclusion.html