Web Components CG -> docs for Custom Elements.

[trusktr]

We have a docs-and-guides channel in the WCCG discord: https://discord.gg/PZH8ucFHp2

It'll be nice to coordinate on web docs. The WCCG started a docs site at https://webcomponents.guide.

[Elchi3]

Hey @trusktr! Thanks for filing this issue! The Docs CG just started its work yesterday! We are wondering if we should talk about Web Components in our next Community Group call. Would you be up for that? We're meeting every 2nd Tuesday, at 5pm CEST. I'm going to sent out an invite for May 6 soon.

We had a few questions:

• Do you have an updating/maintenance plan for the site you've shared?
• What do you think about the docs that live on MDN? https://developer.mozilla.org/en-US/docs/Web/API/Web_components
• Do you know what needs web developers have when it comes to Web Components and how better docs could be helpful to them?
• There is https://2024.stateofhtml.com/en-US/features/web_components/ with some insights. Should we analyze this some more?
• Do you want to invite more people from the WCCG to have a conversation with us?

Looking forward to chat about Web Component docs either here or in the call!

[Elchi3]

In preparation for the W3C Docs CG call on Web Components, I took a look at the survey responses from the 2024 State of HTML survey:

Some survey free form responses specifically on the quality of WC docs:

• Hard to find documentation on making actual web components rather than react
• Lack of good manuals, tutorials, best practices and patterns
• Lack of practical resources, either chunks of references or badly written articles
• no documentation on lifecycle hooks apart from the spec
• Native web components technologies have bad documentation
• Not a lot of examples and documentation around
• Lack of a good introductory tutorial on web components. The existing tutorials all seem to be geared towards people coming from other JS frameworks, but not for someone starting with html

From other free form responses you can derive unanswered questions that web developers have. Possibly a starting point to check in current docs if are helpful to give answers or guidance at all.

• How to make shadow dom elements styleable?
• How to let in styles into the shadow dom? / How to share styles?
• How are you meant to use declarative shadow DOM without repeating the markup? / How to avoid so much boilerplate code?
• When to use Shadow Dom and when not?
• Accessibility of items in the shadow DOM?
• The shadow DOM is extremely tough to set up / too much complexity
• How to communicate data between document and shadow DOM?
• How to install WC's/make them available?

[Elchi3]

@tayloregivens gave a talk on Web Components: https://www.youtube.com/watch?v=dEFfqqJWLwQ. It provided me a great overview into current WC discussions.

Some quotes I found interesting and that maybe hint at how people (don't) adopt WC's currently.

• "There is no marketing team for WC. Enterprises are using them and it's quietly taking over because it is a useful feature but you kinda need specialists and well-resourced teams to pick it apart and figure out how to use it because it's more of a low-level tool. For the average developer, they use it using libraries such as lit or or fast or they might be using it in React if it is implemented under the hood. But most commonly we see it being used on the enterprise scale by more well-resourced teams."

• "Vanilla web components are pretty difficult to use by themselves"

• "We win and move things forward by shipping and working more closely with WC libraries"

• @atopal asked: "How we can see more adoption of WCs?" and Taylore said: "I had to do a lot of research for this talk to really understand where WC's are at." [...] "Find someone in enterprise teams to talk about WCs, but for hobbyist who are using it on a smaller scale, its harder for them to have access to resources and knowledge."

So, this hints that more docs are needed to get the hang of WCs and also that frameworks play a major role here.

[Elchi3]

Brief look into the current content outlines we seem to have. It's not a lot, so the needs expressed above are probably not addressed by the current state of the docs on neither MDN or webcomponents.guide:

MDN

(kept relatively up-to-date)

• Overview
  • https://developer.mozilla.org/en-US/docs/Web/API/Web_components
• Reference
  • Probably more or less complete.
• Guides:
  • Custom elements
  • Shadow DOM
  • Templates and slots
• How-tos
  • None
• Tutorials
  • None

webcomponents.guide

(last updated in 2023?)

• Overview
  • https://webcomponents.guide
• Reference
  • None
• Guides
  • Defining a component
  • Autonomous vs Customized Elements
  • Naming your components
  • Initializing your component
  • Rendering
  • Styling
• How-tos
  • Using Cancellation Signals
• Tutorials
  • Mastodon toot embed