guide: Essentials
afontcu opened this issue · comments
This comment by @bencodezen in discord regarding docs-next:
Our goal in "Essentials" is to get people up and running with just enough and nothing more
Made me think about something that has been on my mind for days. Right now, I see VTU as a toolset with 2 categories of stuff:
- Set 1: basic, "essentials" tools such as
find
,trigger
,setValue
,emitted
, and so on (I believe the list doesn't grow much larger, tbh). - Set 2: advanced stuff: stubbing,
setProps
,findComponent
, and whatever flavour of shallow mounting we end up using.
I think docs should follow this structure. An Essentials category, with everything you need to get up and running if you're writing your first tests with Vue.
Then, and only then, we unveil advanced features which require deeper knowledge.
Does it make sense? Would we be able to "split" all VTU-next features in two sets, or at least "prioritize" them in a way that allow us to teach them sequentially?
I think essentials only needs to focus on the Set 1
content. Thoughts?
The others are useful, but not "essential".
Although complex nextTick
and maybe flush-promises
could go here - it is somewhat essential. Thoughts?
I think we need to get started on this, since the lib itself looking pretty good. Do you have some time to work on this @afontcu or should we ask someone else to pick it up?
I'll have some time this week :) I think I'll set up a PR with a proposal for the sidebar, so we can discuss the overall structure before diving too deep into details. Does it sound good?
I found this bit of Vue Docs Writing Guide quite enlightening: https://vue-docs-next-preview.netlify.app/guide/writing-guide.html#organization
Its goal [the Essentials part] is to provide the 20% of knowledge that will help users handle 80% of use cases
That is an awesome quote, I agree with it for sure. If we can help people test 80% of your components, that would be great.
I think I'll set up a PR with a proposal for the sidebar, so we can discuss the overall structure before diving too deep into details. Does it sound good?
Sure does! I am excited for these docs.
BTW do you think we can keep the essentials generic enough to use them for both V1 and V2 docs? Or would this be too restricting?
BTW do you think we can keep the essentials generic enough to use them for both V1 and V2 docs? Or would this be too restricting?
Hmm yeah, I guess we might? The guiding principles stay the same, so this is doable. Some examples may differ, though, even with the backports implemented lately.
There are several ways to overcome this limitation (tab-based or domain-based code snippets, for instance), but it's worth exploring!