Description
Problem statement
In MDN Web API reference docs, we've been using WebIDL to derive rules for how we want to structure and make the API docs most consistent and useful for web developers.
For example, we said:
- Interfaces always get a page and Interface members are subpages.
- We avoid documenting mixins or dictionaries
- Static API members get the
_staticsuffix in the MDN page slug and in BCD paths. - etc.
For certain WebIDL concepts, or annotations, we are less clear how to consistently document things. For example,
- Maplikes and setlikes
- stringifiers, jsonifiers
- (... and more)
Proposed solutions
Provide MDN authors (and readers) a clear structure for Web API docs by agreeing on how and where to document aspects of Web APIs like maplikes, jsonifiers, (async) iterables etc.
Ideal outcome: Any WebIDL fragment can be taken and it is clear what it will mean in terms of structure and docs on MDN and in BCD. This will make the docs predictable and also it will be easier to generate docs from tooling with consistent structures.
Task list
- Investigate and list which sort of WebIDL concepts exist (use webref or similar)
- For each WebIDL concept, determine if we have agreement how to document it on MDN and how we record it in BCD.
- For each unclear concept, start a discussion and come to a rule.
- Update MDN and BCD per the new rules
- Update MDN meta docs
- Find a place for where WebIDL concepts are explained to web developers (consensus seems to not do this in the glossary)
A good starting point is mdn/browser-compat-data#6367
Priority assessment
- Effort: Unclear, initial research needed.
- Dependencies:
- Community enablement: Discussion will be in the open. Feedback will be welcome.
- Momentum:
- Enabling learners:
- Enabling professionals:
- Underrepresented topics / Ethical web:
- Operational necessities:
- Addressing needs of the web industry:
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 florian@openwebdocs.org.