Doc improvement? WebC's relation to the Web Components spec/tech
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 1.4k
- Forks
- 46
- Avg merge
- 10m
- Merged PRs (30d)
- 2
Description
Hi,
First of all: thanks for all the hard work on Eleventy and related projects such as WebC! My intention with this issue is to prevent confusion for the future users of WebC.
I'm currently getting up to speed with WebC, I was using nunchucks before. Something that confused me quite a bit is the relation between WebC and the Web Components spec/tech.
Because WebC's README uses the term "Web Components" quite regularly my (incorrect!) assumption was that WebC uses Web Components tech somehow (in the compilation step or something). But as @zachleat says in this podcast:
Host: "this has nothing to do with the web platform's Web Components ..."
@zachleat: "yeah correct, it's mostly reusing the same conventions that are used for Web Components"
So I'm sure I'm not the only one that's confused here:
- WebC is named after Web Components.
- The README uses, but not clearly defines, the term "Web Components".
- WebC reuses a lot of the conventions of actual Web Components.
All of this leading up to WebC not actually using any tech underneath Web Components, but naming the WebC components "Web Components".
All this being said my suggestion would be to go back in time and use a different name for WebC and the components it creates, like "VCom" and "Vanilla Components" or something. But that ship (or Delorean) has probably sailed.
My actual suggestions are:
-
Make the exact relation between WebC and Web Components very clear in both the documentation and any communication about WebC.
-
Use the term "WebC Web Components" (abbreviated to WCWC?) instead of the bare "Web Components" in every introductory text where confusion may arise.
So in a couple of places write things like:
WebC is a file format that reuses some of the conventions created for Web Components. WebC allows you to create components which we'll call "WebC Web Components" or "WCWC". These WebC Web Components are not the same as the ones you can create using the Web Components standard.
I'm not sure where to "drop the confusion bomb" of:
You can use WebC to create WebC Web Components that are Web Components.
But maybe that's something that should live deep in the WebC docs.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing README.md, especially its introductory uses of “Web Components,” and compare them with the linked Web Components reference. Update the introductory documentation to explain WebC’s relationship to the Web Components standard and distinguish WebC components from platform Web Components wherever confusion may arise; the documentation should be consistent and unambiguous when finished.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, web-dev
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100