Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OWD project: Mixin docs on MDN #23

Closed
43 of 52 tasks
Elchi3 opened this issue Mar 2, 2021 · 4 comments
Closed
43 of 52 tasks

OWD project: Mixin docs on MDN #23

Elchi3 opened this issue Mar 2, 2021 · 4 comments

Comments

@Elchi3
Copy link
Member

Elchi3 commented Mar 2, 2021

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.

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.
  2. BCD stops exposing mixin data and exposes data under real interfaces instead.

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
Copy link
Member

Should we add HTMLOrForeignElement to the list?

@sideshowbarker
Copy link
Contributor

Should we add HTMLOrForeignElement to the list?

I think we should

@Elchi3
Copy link
Member Author

Elchi3 commented Apr 12, 2021

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 Elchi3 mentioned this issue Jun 15, 2021
@Elchi3
Copy link
Member Author

Elchi3 commented Sep 7, 2021

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.

@Elchi3 Elchi3 closed this as completed Sep 7, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants