Sidebar proposal for docs

[afontcu]

Closes #17

This PR splits the main content into 3 sections:

• Essentials: its goal is to "is to provide the 20% of knowledge that will help users handle 80% of use cases".
• VTU in depth: its goal is to provide knowledge to cover up to 95% of use cases.
• Extending VTU: its goal is to provide tools&resources to extend VTU capabilities.

disclaimer: numbers are totally made up 😂

I wrote a tiny proposal for content on each section, check out the markdown.

Also, I tried to keep Essential to its bare minimum, trying to convey the feeling that testing your components is not an advanced skill, but something really doable.

Outline

Unanswered questions

• what to do with "Crash Course"? Couldn't find the right place for it, even though it is great content.
• I think global.components is going to be quite useful but I'm not sure where it should be mentioned.
• should we have a specific page for VueWrapper / DOMWrapper? (I'd say no, but I want to hear your thoughts).
• should we have a FAQs page? ("find or findComponent?", "how do I write e2e tests?")
• should we have a "Guiding Principle" page?
• do we need to cover the whole API in the guide? (I'm thinking about stuff such as attachTo).

Any other missing bits? Something's not necessary? Things I got wrong? Better alternatives? Suggestions? :)

btw: The Writing Guide from docs-next is a great source of knowledge to reflect upon when writing docs. Also, I tried to mirror docs-next while creating and naming sections.

[lmiller1990]

Had no seen the Writing Guide... great stuff.

First impression is this looks great! I will think about your questions for a few hours and give my thoughts.

PS: should we use Vitepress for docs? It is using Vue 3, so we can have it in the same repo as the main lib. If we want to migrate, better now than after we get started writing.

[lmiller1990]

I wonder if we should switch the order of "passing data" to be first, then conditional rednering, then and "handling events". To me, passing data is more basic - iirc the first thing Vue introduces is:

new Vue({
  data: {
    // ...
  }
})

Additionally, passing data transitions well into conditional rendering:

const Comp = {
  template: '<div><p v-if="show">Hello</p></div>',
  data() {
    return { show: true }
  }
}

mount(Comp)

// assert show is present
// use `data` mounting option to set show: false
// it works!

Also feel free to completely change/move a crash course. It's a lot of information all at once - should that come at the end of essentials? We could link to that on the intro - eg "If you are already familiar with testing, and just want to see the API, check out "a crash course". Otherwise, get started with "essentials - mounting a component" or something.

I'd like to get writing so we can move to beta sooner rather than later. I think we should at least have the articles completed in essentials - although it need not be 100% perfect for beta.

Can you allocate an article to me (and any notes/important info you would like to highlight)?

I also think "migrating" is probably an important one. This one is quite easy to write without much discussion - if anyone is has time, feel free to jump on this one.

[lmiller1990]

I like where this is going, left some thoughts (I won't say recommendations - docs and their structure is much less objective than code).

[afontcu]

(thanks for your kind words!)

I wonder if we should switch the order of "passing data" to be first, then conditional rendering, then and "handling events".

sounds good to me, too! I moved Passing Data a bit lower because I assumed it would container setProps as well, which I believe is a bit more advanced. But we can work it out.

Also feel free to completely change/move a crash course. It's a lot of information all at once - should that come at the end of essentials? We could link to that on the intro - eg "If you are already familiar with testing, and just want to see the API, check out "a crash course". Otherwise, get started with "essentials - mounting a component" or something.

That's a good idea. After reading this, I feel the Crash Course and the stuff we're outlining here have a different nature. One is a fast/happy path, and other content are "city streets".

If we end up with more Tutorials, we can even have a separate section for them.

Can you allocate an article to me (and any notes/important info you would like to highlight)?

The one you feel like writing :) You've been quite involved with the development of stuff such as Async/Suspense and Shallow/Stubs, so that might make sense!

---

I had this idea where, instead of writing a full-blown section, we could first evolve each section from a blank page -> page with headings (with a summary of content for each one) -> page with headings and code examples -> full-blown section. This way, we might see blind spots, duplicated content, inconsistencies… without having anyone invested much time in a single section.

[lmiller1990]

I agree about the crash course. We can probably use some content from there elsewhere, so I won't delete it, but I like the idea of short articles that focus on 1-2 specific concepts.

I had this idea where, instead of writing a full-blown section, we could first evolve each section from a blank page -> page with headings (with a summary of content for each one) -> page with headings and code examples -> full-blown section. This way, we might see blind spots, duplicated content, inconsistencies… without having anyone invested much time in a single section.

This makes sense. I like how you have left some basic ideas on each page - makes it much easier for someone to pick up an article.

Let's merge this and do what you suggested... let it evolve bit by bit.