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.
- 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.
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
- MDN stops documenting mixins directly.
- BCD stops exposing mixin data and exposes data under real interfaces instead.
Task list
MDN tasks
The following mixin pages need to be updated/removed per the new guideline.
BCD tasks
The following mixin data needs to be updated/removed per the new guideline.
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.
Documentalready and are now also available withWorker.Priority assessment
This table checks this project against the OWD prioritization criteria.
Proposed solutions
Task list
MDN tasks
The following mixin pages need to be updated/removed per the new guideline.
BCD tasks
The following mixin data needs to be updated/removed per the new guideline.