OWD project: Mixin docs on MDN

[Elchi3]

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.
  • How to represent 'mixins'? 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.

Criteria	Assessment
Effort	Large. About 22 existing mixin documentation trees exist. For each page tree there are about 5-50 pages to rework and new pages to be written as mixin members are often only documented for half of the real interfaces.
Dependencies	Needs to get done in compat data and in mdn/content at the same time. Requires redirects/moving pages to work on MDN.
Community enablement	Reading specs and understanding mixins and IDL can be complex, yet the work is shareable
Momentum	BCD collaborators (foolip, Daniel) and MDN content writers who constantly run into missing guidance for how to document mixins (Chris, Rachel, Joe) seem to really like having some momentum here. Also, the specs are usually stable for the fundamental APIs
Enabling learners	It would help to be less confusing. NonDocumentTypeChildNode.nextElementSibling is very weird; Element.nextElementSibling is more accessible.
Enabling professionals	This rework will bring more attention to detail and consistency to the docs which professionals would appreciate
Underrepresented topics / ethical web	N/A
Operational necessities	It is often a blocker that there are no clear guidelines on how to document a new API that uses mixins. (see e.g. the AriaMixin case that Rachel ran into). Once a mixin guideline is approved (first task of this project), there is no blocker anymore, though.
Addressing needs of the Web industry	It does clear up very confusing compat data by a lot. So it makes compat tables more clear and probably improves web developer's perception of web compat.

Proposed solutions

1. MDN stops documenting mixins directly.
   • This has been agreed on in API structure conventions: mixins mdn/content#1940
2. BCD stops exposing mixin data and exposes data under real interfaces instead.
   • This had been agreed on in Stop exposing mixins; instead add them to their target interfaces 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

[wbamberg]

Should we add HTMLOrForeignElement to the list?

[sideshowbarker]

Should we add HTMLOrForeignElement to the list?

I think we should

[Elchi3]

Should we add HTMLOrForeignElement to the list?

Hm, this didn't make the list in the first place because it has no BCD. Not sure how common it is for mixin pages to have no BCD but it can happen since the BCD for them is nonsense often.

Anyway, I added it.

[Elchi3]

This is all done except for GlobalEventHandlers and
WindowEventHandlers. I opened mdn/browser-compat-data#12290 for BCD which, together with mdn/browser-compat-data#7545 could be proposed as a new project that deals with event mixins and event compat data generally.