Add a glossary #2199
Add a glossary #2199
Conversation
✅ Deploy Preview for vuejs ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
|
@skirtles-code thank you for working on this! Even in this unpolished state the draft looks very promising.
I would say "yes". "What is composable" is probably the most common question I hear about Vue and you started right from it 😅
IMO, they are good enough. Perfect level of detail will come with iteration and community contributions. Different terms will naturally have different level of detail because the scope is very different there.
IMO, glossary should aim for formal definitions
Both! Because there will be both kinds of the target audience. |
src/glossary/index.md
Outdated
|
|
||
| Macros have limitations on their use that don't apply to normal JavaScript code. For example, you might think that `const dp = defineProps` would allow you to create an alias for `defineProps`, but it'll actually result in an error. There are also limitations on what values can be passed to `defineProps()`, as the 'arguments' have to be processed by the compiler and not at runtime. | ||
|
|
||
| These macros are conceptually similar to dynamic imports using `import()`. While `import()` looks a lot like a function call, it's actually special syntax that gets processed by the bundler as part of the build. Like with `defineProps()`, we can't create an alias using `const myImport = import`. There are also restrictions on exactly what syntax can be used to pass values to the `import()` 'function', so that the bundler can understand the values. |
There was a problem hiding this comment.
The analogy here isn't 100% correct and might be misleading, since dynamic import() is in fact a native JavaScript feature. It's just bundlers happen to use it (with syntax limitations) as a form of compilation hint.
There was a problem hiding this comment.
I've removed this paragraph.
The motivation behind including it was to try to make Vue's macros seem more relatable, and less like 'Vue being weird'. Native import(), used without a bundler, still has some similarities to the Vue macros, in that it isn't a true function and can't be aliased.
But I can see how it could be confusing. Trying to explain one unfamiliar concept by analogy to another unfamiliar concept is probably not going to have the effect I was aiming for.
| Rather than creating DOM nodes directly, Vue components generate a description of what DOM nodes they would like. These descriptors are plain JavaScript objects, known as VNodes (virtual DOM nodes). Creating VNodes is relatively cheap. | ||
|
|
||
| Every time a component re-renders, the new tree of VNodes is compared to the previous tree of VNodes and any differences are then applied to the real DOM. If nothing has changed then the DOM doesn't need to be touched. | ||
|
|
There was a problem hiding this comment.
Worth adding a note that Vue improves virtual DOM runtime performance with compilers, since many new users nowadays assume virtual DOM to be associated with bad performance due to Svelte / Solid's marketing.
There was a problem hiding this comment.
I have added a paragraph at the end about 'Compiler-Informed Virtual DOM'.
|
Any particular reason why all terms start with lowercase? It feels a bit weird to be honest. |
Co-authored-by: Evan You <[email protected]>
Co-authored-by: Evan You <[email protected]>
Co-authored-by: Evan You <[email protected]>
Yeah. I was aiming for the kind of casing you'd see in a dictionary, with words written in the case they would usually have if they were used in the middle of a sentence. So Composition API and Single-File Component get capital letters, whereas terms like props are just lowercase. For reference, the Angular glossary uses this same casing convention, though the React glossary does not. |
Deployed: https://deploy-preview-2199--vuejs.netlify.app/glossary/
The motivation is to help developers to understand what key technical terms mean in a Vue context. e.g. What is a 'compiler macro' or a 'fragment'? These are intended to be relatively brief introductions to the terms, with links to read more.
The main guide could link to these entries when a term is potentially unclear to the reader, though I haven't currently added any such links.
In some cases, the need for a glossary entry could be an indication that we need to do a better job of explaining a concept in the guide. However, the guide has its own specific role, and trying to clarify the exact meaning of a term can potentially derail the flow or require discussion of topics that haven't been covered yet. The glossary doesn't need to bound by those concerns.
Some open discussion points:
Some initial questions I asked when I first opened this PR:
Some glossaries we might want to use as reference points: