Curating the web platform's data and documentation

• Past
• Confirmed
• Breakout Sessions

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.

Agenda

Chairs:
Florian Scholz, Will Bamberg, Estelle Weyl, Vinyl Da.i'gyu-Kazotetsu

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.

Goal(s):
Discussing curation of documentation, compatibility data. Exchanging feedback among repo maintainers

Agenda:

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

Materials:

• minutes
• Session proposal on GitHub

Track(s):

• Feature lifecycle

Minutes

 Read minutes

Export options

Personal Links

Please log in to export this event with all the information you have access to.

Public Links

The following links do not contain any sensitive information and can be shared publicly.

• Download as ics