Misleading documentation - Section "Getting started"

[PatrickRoesler]

I wasn´t able to find the right place to report my problem, so I decided to create an issue. Please feel free to tell me, where I should place problems like the following:

Yesterday I started working with vue.js. After reading and understanding the "Getting started" section (https://vuejs.org/v2/guide/index.html) I started developing. Now, my colleagues told me, that I did something wrong: For each div-container I created a new Vue instance. So instead of creating one application with many components I created many application without any components.

I told to my colleagues, that I exactly did, what the documentation says. And they aggreed: The docs suggests to create many applications, so it´s misleading.

It would be very nice, if someone could make this point clear in the documentation.

Thanks in advance

Patrick

[phanan]

Thanks for opening the issue. Can you point us to the section that advises creating multiple applications?

[PatrickRoesler]

It is not explicitly said, that you should create multiple applications but the reader gets this impression.

Under the headline "Declarative Rendering" an instance referencing on the div with id "app" is created.
Then in the same section there is a div with id "app-2" and again a new instance referencing "app-2" is created.

To me it looks like every div container should get it´s own application instance.

Edit: It´ s not only this 2 occurrences. It´s the same in the examples below.

[phanan]

Interesting :) I'd say this is the first time we get this feedback. How would you imagine this to be less confusing for beginners?

[sarahdayan]

Hey @phanan @PatrickRoesler, here's an idea to clarify and avoid confusion:

1. Instead of using app, app-2, app-3, etc. only do app. The examples aren't reused in the page anyway so it seems fine to go with the same example.
2. Under the Declarative Rendering section, in the paragraph preceding the code sample (or the one after), add a short sentence to explain that this is where the full Vue app is rendered. It can sometimes be confusing for people who aren't used to full-JS libraries like Vue not to have more HTML, so it would probably help to explain that this is our entry point and that everything else happens within the created Vue instance.

What do you folks think, would this help? If yes, I can PR 🙂

[phanan]

Thanks for chiming in @sarahdayan! The main reason why the IDs are different across the page is that the exact same scripts are executed under the hood (you can verify this by looking at the page's source code). Using only 'app' would break this connection.

As said above, this literally is the first time we/I have this feedback. TBH, personally I don't see this as an issue and am tempting to close it unless more people say otherwise.

[sarahdayan]

@phanan Oh that’s true I forgot about the fact that the examples are executable!

Do you think there would be value in explaining more about what is a Vue app and how it attaches itself to a single global DOM element, then fully controls it?

As you said, this might be unnecessary since this feedback is unusual.

[phanan]

Do you think there would be value in explaining more about what is a Vue app and how it attaches itself to a single global DOM element, then fully controls it?

Yeah, I think this might be beneficial for beginners who are absolutely new to a framework. Do you reckon this paragraph can be written in a way that conveys our new message too?

We have already created our very first Vue app! This looks pretty similar to rendering a string template, but Vue has done a lot of work under the hood. The data and the DOM are now linked, and everything is now reactive. How do we know? Open your browser’s JavaScript console (right now, on this page) and set app.message to a different value. You should see the rendered example above update accordingly.

A PR is most welcome naturally :)

[sarahdayan]

@phanan On it 🙂