Add 06-05-2025 Docs CG meeting

meetings/2025-05-06.md

@@ -0,0 +1,80 @@
+# W3C Docs CG call, 2025-05-06
+
+Present: Florian Scholz, Lola Odelola, François Daoust, Justin Fagnani, Will Bamberg, Eric Meyer, Jonathan DeWitt, Jonathan Neal, (several others who joined later)
+
+Chair: Florian
+
+Note taker: Will
+
+Joining info:
+
+To join the video meeting, click this link: https://meet.google.com/jdp-xvka-hyk
+Otherwise, to join by phone, dial +49 40 8081617306 and enter this PIN: 544 514 889#
+To view more phone numbers, click this link: https://tel.meet/jdp-xvka-hyk?hs=5
+
+## Agenda
+
+1. Welcoming more new folks
+2. Web Component docs
+    - Issue: https://github.com/w3c-cg/webdocs/issues/1
+    - Interpreting the survey for documentation needs https://2024.stateofhtml.com/en-US/features/web_components/
+    - webcomponents.guide
+    - MDN docs: https://developer.mozilla.org/en-US/docs/Web/API/Web_components
+
+## Notes
+
+### Web Component Docs
+
+- Issue: https://github.com/w3c-cg/webdocs/issues/1
+- Interpreting the survey for documentation needs https://2024.stateofhtml.com/en-US/features/web_components/
+- https://webcomponents.guide/
+- MDN docs: https://developer.mozilla.org/en-US/docs/Web/API/Web_components
+
+Justin: vanilla versus using a library is a big issue in WC world.
+
+Lola: MDN usually documents vanilla, not frameworks. But in many places MDN needs to refer to frameworks, because most people use them through frameworks (e.g. WebRTC).
+
+Justin: WC are perceived as competing with frameworks like React. WC are mostly developed through libraries, and when we point people at the low-level it looks really bad compared with React.
+Libraries want common conceptual low-level docs that we can point to from the library docs.
+
+Florian: it's hard to keep up with framework docs.
+
+Will: It has not been successful to document frameworks on MDN. How much are vanilla WC docs directed at framework authors vs. web developers?
+
+Justin: small but vocal contingent want people to be able to write vanilla WC, without dependencies. Vast majority use frameworks. There is a base level of conceptual documentation that doesn't belong in the spec but could well live in MDN (e.g. shadow DOM). Vanilla WC features are still available in WC frameworks, so can still be useful to FW users.
+
+Justin: https://www.webcomponents.org/introduction was the original site for WC, and still has a lot of juice. https://github.com/webcomponents-cg/docs-and-guides/blob/main/plan/outline.md is an outline for a new site that hasn't been created yet. Docs for Lit would like to link out to somewhere like MDN for conceptual docs such as shadow DOM.
+
+Justin: someone could use a custom element from Lit, but not need the Lit docs to understand how to use it. So the "using web components" docs can be framework-agnostic.
+
+Jonathan: Frameworks sometimes experience the same thing. ShadCN users use a plethora of React components with their own API voices and gotchas. ShadCN picks the most similar and smooths over the styling.
+
+Lola: on MDN we're mainly documenting _writing_ WCs, not using them. Is part of the request that _using_ WC documentation should live on MDN
+
+Florian: https://diataxis.fr/ is a model for writing documentation. Four sectors, reference/how-to/tutorial/explanation. Helpful in coming to an outline, and we can see that many of these sectors are under-represented on MDN.
+
+Justin: not sure if appropriate for MDN, but want a marketing page for WC, not just users and developers, but decision-makers. High-level description of what they are and why you might want to use them.
+
+Lola: would be hesitant to create marketing in the same way that, say, React has marketing, but explaining the motivation for a tech to decision-makers might be different.
+
+Florian: Taylore quote from https://github.com/w3c-cg/webdocs/issues/1#issuecomment-2830416341: marketing in the sense that web devs don't have a well-explained justification for using WCs outside a framework.
+
+Will: "marketing" on MDN in the sense of giving explanations for why a web platform feature is useful, is fine on MDN, we do this all the time, otherwise the docs are incomplete.
+
+Florian: next steps are to assess Justin's input here and the outline, compare with the survey and see whether the outline seems like it will address the issues.
+
+Lola: in an ideal world, how would these docs interact? Would you just have docs for framework and link to MDN, or would there be some other docs?
+
+Justin: we maintain lit.dev and have a section on shadow DOM. we have two links near the top that do to dev.google.com (web.dev). Would like MDN to have the best shadow DOM doc, and link there for the details.
+
+Lola: Is there some initial contribution you could make to MDN to make e.g. the shadow DOM docs be as good as possible.
+
+Justin: yes, a collaboration with the MDN folk would be awesome. MDN folk can help us understand how to contribute to MDN.
+
+Florian/Will: We're happy are happy to help with that.
+
+### Next steps
+
+- Meet with WCCG folks again to discuss more (either in Docs CG calls or separately)
+- Develop a content outline that takes into account diataxis, as well as needs identified from the survey
+- Look at the docs from the perspective of two audiences: people writing custom elements from scratch, and people using a library like Lit to integrate WCs.