Provide better documentation about the relationship between web-features and other projects

[ddbeck]

We could improve the web-features site to explain, possibly with a diagram, the connections between web-features, BCD, caniuse, MDN, and so on. Inspired by the following exchange:

Originally posted by @FrankConijn in #3809:

Regarding the different sources and web pages however, things are getting utterly confusing. Two pages for initial-letter (https://caniuse.com/wf-initial-letter and https://caniuse.com/mdn-css_properties_initial-letter,mdn-css_properties_initial-letter_normal) and three related Github pages for browser support (https://github.com/web-platform-dx/web-features/, https://github.com/mdn/browser-compat-data and https://github.com/web-platform-dx/web-features/)?

I'd need a YouTube video or a good article that explains how they are all related and why it's necessary to have so many pages. I'm lost.

Originally posted by @ddbeck in reply

I'm sorry it's confusing. It is confusing. Here's a rough explanation of how these things are related:

• mdn/browser-compat-data (also known as BCD) tracks browser support in HTML, CSS, APIs, JavaScript, WebAssembly, and so on. It's very granular (e.g., the Fetch API has over 75 named entries, one for each interface, method, and even many function parameters and the like).
• web-features (this repo) provides IDs for high-level web platform features, to help link data across different tools and sources (e.g., specs, BCD, web platform tests, Chrome Platform Status entries, Interop, caniuse, and so on). Then we use that information to aggregate or generate support information (i.e., to calculate a Baseline status). The data we publish is used by consumers in various ways.
• caniuse is probably the most complex example of a BCD or web-features data consumer. It has its own original feature pages, pages generated from BCD (the mdn- pages), and pages based on web-features (the wf- pages).
• MDN uses BCD to generate compatibility tables, but uses web-features data to show status banners at the top of each reference page.

Our long-term aspiration here is to help reduce the complexity, by giving common identifiers to web platform features across different sites, so you'd be able to know that (for example) a State of HTML survey question and a caniuse feature page refer to the same thing. The web's legacy is long, however, and we only just started this project a couple of years ago. It's slow ship to turn.

I'll file an issue to try to improve our documentation on this point.

[NiklasMerz]

A diagram that show how BCD, web-features, Baseline etc. are interconnected sounds like a great idea. This should be on a page that every consumer (caniuse, MDN, caniwebview etc..) of this data can link to if they need to explain how the data is computed and where it's coming from.

It took me way to long to finally understand this and a picture is worth a thousand words.