project icon indicating copy to clipboard operation
project copied to clipboard
verified publisher icon openwebdocs

OWD project: Doc structures for WebIDL concepts

Open Elchi3 opened this issue 2 years ago • 3 comments

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 _static suffix 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

  • [x] 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 https://github.com/mdn/browser-compat-data/issues/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 [email protected].

Elchi3 avatar Jun 08 '23 15:06 Elchi3

See also https://github.com/mdn/content/issues/7844, https://github.com/mdn/content/issues/6891

Josh-Cena avatar Jun 24 '23 17:06 Josh-Cena

I used WebRef to start building a list of concepts to document, that is, concepts actually in use. Some will lead to significant work; others should be reasonably quick to deal with.

(This list is a WIP)

Extended attributes

Legacy extended attributes

Other extended attributes

Special types

  • [ ] setlike<…>
  • [ ] maplike<…>
  • [ ] sequence<…>
  • [ ] iterable<…>
  • [ ] record<…>
  • [ ] Promise<…> (especially Promise<undefined>)
  • [ ] Array<…>
  • [ ] FrozenArray<…>
  • [ ] typedef
  • [ ] Pseudo-typedef (( … or … ))
  • [ ] any

Special operations

  • [ ] getter (named)
  • [ ] getter (unnamed
  • [ ] stringifier
  • [ ] inherit attribute

Special typedefs

  • [ ] CSSOMString
  • [ ] USVString
  • [ ] DOMString
  • [ ] ByteString
  • [ ] DOMHighResTimeStamp
  • [ ] DOMTimeStamp

Others

  • [ ] callback, how to document these?

teoli2003 avatar Jul 26 '23 15:07 teoli2003

The discussion for iterable, maplike, setlike has been started here: https://github.com/orgs/mdn/discussions/707

Elchi3 avatar Aug 19 '24 08:08 Elchi3