Curating the web platform's data and documentation

[Elchi3]

Session description

Open Web Docs is a nonprofit open collective that curates web platform documentation and data for the benefit of web developers and the ecosystem's tooling. In this session we want to talk about how we work and how you (as a spec editor or implementer) can collaborate with us.

We want to talk about how specs and web platform features go through a "pipeline" of repositories and why that is important for us as documentation and data curators.

1. A new spec gets authored and picked up by: https://github.com/w3c/browser-specs
2. Spec definitions and in particular IDL definitions get parsed by reffy and https://github.com/w3c/webref
3. Web platform features get identified from webref and continuously tested by https://github.com/openwebdocs/mdn-bcd-collector
4. If a browser ships an identified feature, https://github.com/openwebdocs/mdn-bcd-collector signals that to https://github.com/mdn/browser-compat-data
5. https://github.com/mdn/browser-compat-data gets released and spreads the information to MDN, caniuse, caniwebview, linters, specs, other tooling and reporting.
6. At this stage, the feature is also marked in need of technical documentation via https://openwebdocs.github.io/web-docs-backlog/
7. https://github.com/web-platform-dx/web-features defines a feature id for the new feature and calculates a "baseline" status allowing it to be talked about in a consistent way in even more places.
8. Web developers start using the feature more broadly and adapt it as the feature hopefully transitions to "baseline high" over the course of the next few months.
9. (if the feature gets deprecated and we take steps to signal to users to move off of it again)

There is probably more to it but this should give you an idea of our "pipeline". The above is sort of the "golden path". Of course, things can go sideways in several ways and, in the worst case, that will lead to non-existing docs and compat data:

• Specs don't make it into the browser-specs repo or don't have standing: good
• Browsers implement things without a spec and we have to maintain custom IDL files and document features as non-standard
• Features are specced but never see implementation (we shy away from curating these, "spec fiction").
• Features sit behind a flag for a long time (and change drastically, so we don't curate docs and data until we have been promised with some stability)
• Bugs in any of the above repositories
• Shortage of maintainers, technical writers, developers, curators, in any of the repositories.

Session goal

Discussing curation of documentation, compatibility data. Exchanging feedback among repo maintainers

Additional session chairs (Optional)

@wbamberg, @estelle, @queengooborg

Who can attend

Anyone may attend (Default)

IRC channel (Optional)

openwebdocs

Other sessions where we should avoid scheduling conflicts (Optional)

7

Instructions for meeting planners (Optional)

No response

Agenda for the meeting.

1. Short presentation about OWD's web platform data and documentation curation pipeline
2. Discussion

Links to calendar

• 2024-09-25, 11:15 - 12:15

Meeting materials

• Minutes

[tpac-breakout-bot]

Thank you for proposing a session!

You may update the session description as needed and at any time before the meeting, but please keep in mind that tooling relies on issue formatting: follow the instructions and leave all headings and other formatting intact in particular. Bots and W3C meeting organizers may also update the description, to fix formatting issues or add links and other relevant information. Please do not revert these changes. Feel free to use comments to raise questions.

Do not expect formal approval; W3C meeting organizers endeavor to schedule all proposed sessions that are in scope for a breakout. Actual scheduling should take place shortly before the meeting.