Create a webcomponents guide tailored to usage with Elm
mfeineis opened this issue · comments
gampleman suggested on discourse to add a focused webcomponents how-to specifically for Elm. I really like this
https://discourse.elm-lang.org/t/improved-documentation-for-flags-ports-and-custom-elements/5552/5
- Look for good concise tutorials for the specific parts we actually need from the spec, maybe they're out there
- Also mention that extending builtin elements is a problem because of Safari https://bugs.webkit.org/show_bug.cgi?id=182671 which kind of has a polyfill https://github.com/ungap/custom-elements-builtin
- Is this within scope for the repo?
- Do the thing?
- Apply suggestions in comments in another pass
- Add a section about Attributes vs Properties
- Review?
Still no nice tutorials out there that I can find with my google foo. It doesn't really matter if this is within scope for this repo, I'll write up something and then we'll decide.
- Suggestion: Extended built-ins cannot be used from Elm since the vdom library doesn't support it
- Suggestion:
I think it'd read better if there was a newline after the first sentence.
You can also trim that sentence down so people will get a clear understanding of what they are reading more quickly. For example.
Current:
This document is meant to be a practical usage guide to the various web components specs with the goal to provide you with the necessary tools to interop with web APIs that are not yet covered by Elm's core packages. The reason this guide exists is that most tutorials and documentation on web components just dump all the specs and some basic usage examples on you assuming that you already know the intricate details of why specific parts of the spec exist in the first place and what use case they try to solve. This situation can be daunting even for experienced web developers and even more so for newcomers. We aim to be as concise as possible while also providing sufficient information to get you up and running in no time.
Alternative:
This is a practical guide to the somewhat confusing web component specs.
Most documentation on web components show the spec and a basic usage example, assuming that you already know the intricate details of why specific parts of the spec exist in the first place and what use case they try to solve. This situation can be daunting even for experienced web developers and even more so for newcomers.
This document tries to be as concise as possible, while also providing enough information to get you up and running.
Generally, I'd go through and try to tighten things up. Can any words be dropped? Can any sentences become bulleted lists? Are the places where a paragraph can be broken up? I personally think all these things make for easier reading in online documentation.
- Suggestion: I do think the beginning portion is a little too long, specificay regarding things like the history of import and require.
- Reference vdom problems with customized built-ins elm/virtual-dom#156