Reorganize sidebar and some content; cannibalize reactivity page #1086

chrisvfritz · 2017-08-18T21:59:17Z

What I did

Split Advanced sidebar category into smaller, more meaningful categories.
Renamed some page titles.
Removed Reactivity page, as I think a lot of its content may actually be too advanced for end users, but I've kept it hidden for future adaptation into a detailed Contributor's Guide to Vue's internals. Though removed, the essential information has been spread out throughout the Guide and API.
- API entries for mounted and updated now cover vm.$nextTick.
- Covered change detection caveats for objects (including Vue.set/vm.$set) under List Rendering, where the caveats for arrays were already listed.
- Reorganized List Rendering, most notably putting the component section at the end. I discovered that many people were skipping the rest of the page once they got to components, since they hadn't learned components yet. Then they never came back. The result is that many people never even read about array change detection and some of the more niche v-for features. 😬
- Rewrote The Vue Instance, as many beginner and intermediate users were glazing over at terms like constructor, proxy, etc, leading to many assuming that the reactivity system is more complicated than it is (and not absorbing essential tips). I also tried to make some essential information more clear, e.g. data that starts out empty or non-existant still has to be registered with a starting value.
- Added note about the devtools on the Installation page
I noticed we were using a combination of -> and => to represent expression return values, so I arbitrarily standardized on =>.
Moved Filters to its own page, removing it from Syntax, because it's not really an essential feature.

Questions

Are the new sidebar categories meaningful to you? When you see what's inside them, are they the kinds of pages you'd expect to see? Is there anything that feels out of place?
Do the new page titles make sense to you?
How is this intro paragraph of the devtools? Reading this as a user who has just decided to install Vue, do you feel it will entice people enough to click through to learn more?
In the rewrite of The Vue Instance, I've vastly simplified the explanation of the reactivity system. In that simplification, are there any details I've left out that you feel are essential for users to build successful applications, avoiding common mistakes?
With the reorganization of List Rendering, do you feel the page still flows well? Do you feel the sections are generally ordered by most to least essential?

phanan · 2017-08-19T16:33:07Z

src/v2/guide/instance.md

@@ -16,46 +16,68 @@ var vm = new Vue({

 Although not strictly associated with the [MVVM pattern](https://en.wikipedia.org/wiki/Model_View_ViewModel), Vue's design was partly inspired by it. As a convention, we often use the variable `vm` (short for ViewModel) to refer to our Vue instance.

-When you instantiate a Vue instance, you need to pass in an **options object** which can contain options for data, template, element to mount on, methods, lifecycle callbacks, and more. The full list of options can be found in the [API reference](../api/#Options-Data).
+When you create a Vue instance, you pass in an **options object**. The majority of this guide describes how you can use these options to create your desired behavior. For reference, you can also browse the full list of options can in the [API reference](../api/#Options-Data).


full list of options in, not can in.

phanan · 2017-08-19T16:33:34Z

src/v2/guide/instance.md

 ```

-Although it is possible to create extended instances imperatively, most of the time it is recommended to compose them declaratively in templates as custom elements. We will talk about [the component system](components.html) in detail later. For now, you just need to know that all Vue components are essentially extended Vue instances.
+We'll talk about [the component system](components.html) in detail later. For now, just know know that all Vue components are also Vue instances, and so accept the same options object (except for a few root-specific options).


Duplicate know.

phanan · 2017-08-19T16:34:52Z

src/v2/guide/instance.md

+vm.a // => 3
+```
+
+When this data changes, the view will re-render. It should be noted that properties in `data` are only **reactive** if they existed when the instance was created. That means if you add a new property, like:


Isn't "data" plural?

Technically, yes, but in practical use I think most people treat it as singular, e.g. "My data is backed up."

@phanan I'm still open to changing it though. What do you think?

phanan · 2017-08-19T16:36:02Z

src/v2/guide/instance.md

+  visitCount: 0,
+  hideCompletedTodos: false,
+  todos: [],
+  errorMessage: null


I'd suggest error instead of errorMessage, as a "message" would imply a string type.

Will do, though in this case, I'd still actually still have errorMessage be null when it'll be a string later. The reason is a blank error message can still mean something different than a non-existent one.

phanan · 2017-08-19T16:36:49Z

src/v2/guide/instance.md

-Each Vue instance goes through a series of initialization steps when it is created - for example, it needs to set up data observation, compile the template, mount the instance to the DOM, and update the DOM when data changes. Along the way, it will also invoke some **lifecycle hooks**, which give us the opportunity to execute custom logic. For example, the [`created`](../api/#created) hook is called after the instance is created:
+Each Vue instance goes through a series of initialization steps when it's created - for example, it needs to set up data observation, compile the template, mount the instance to the DOM, and update the DOM when data changes. Along the way, it also runs functions called **lifecycle hooks**, giving users the opportunity to add their own code at specific stages.
+
+For example, the [`created`](../api/#created) hook can be used to run code after an instance is created:


You mean can be use to run after?

In this case, can be used to run code after does actually say what I mean. What meaning does it have for you?

Oh, I misread it then. Yeah, it makes perfect sense to me now.

phanan · 2017-08-19T16:37:52Z

src/v2/guide/reactivity.md.hidden

+!!!!!!!!!!!!!!!!!!!!!!!!!!
+!! NOTE FOR TRANSLATORS !!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!! Don't both translating changes to this page yet, !!


Don't bother?

chrisvfritz · 2017-08-20T16:29:08Z

@phanan Thanks for your excellent review. 😻 Great attention to detail!

hootlex

Great job, Chris.

I think the new sidebar categories are a nice improvement. Easy to navigate and contain the expected content. 🙂 Maybe the Transitions & Animation can go above Reusability & Composition but I am not sure since the latter contains some more advanced features like JSX and Plugins. Also, I wonder why Single File Components page is under tooling. Wouldn't it fit better in the Components category?
Yes!
I like it, a small screenshot of DevTools in action would also look nice.
It's just fine.
Still good, didn't even notice the reorganization. ☺️ How about adding a warning on the key section to note that it's required when iterating components? I'd also like to have a warning in the array caveats section, just to draw attention.

hootlex · 2017-08-21T10:03:54Z

src/v2/guide/filters.md

+<div v-bind:id="rawId | formatId"></div>
+```
+
+<p class="tip">Vue 2.x filters can only be used inside mustache interpolations and `v-bind` expressions (the latter supported in 2.1.0+), because filters are primarily designed for text transformation purposes. For more complex data transforms in other directives, you should use [Computed properties](computed.html) instead.</p>


This paragraph repeats the way of using filters.
The part "(the latter supported in 2.1.0+)" can be moved to the intro paragraph, so this can be: "Filters are primarily designed for text transformation purposes. For more complex data transforms....."

Nice catch! I just removed the redundancy. 🙂

hootlex · 2017-08-21T10:22:23Z

src/v2/guide/instance.md

+      |- EditTodoButton
+   |- TodoListFooter
+      |- ClearTodosButton
+      |- TodoListStatistics


I am not sure if it's a good idea to show an example component tree at this point. My concern is that even though it's just an example, people with little experience may get confused or try to follow it as a rule.

If you are going to keep it, maybe it's safer to make it more general. For example:

Root Instance |- TodoList |- TodoItem |- CreateTodoItem |- ShowTodoItem ...

Thanks for bringing this to my attention! I'll do a little more user testing on this part.

chrisvfritz · 2017-08-21T18:03:01Z

Thanks for the review @hootlex! 😄

Maybe the Transitions & Animation can go above Reusability & Composition

I might be misunderstanding, but isn't it already above Reusability & Composition? If you're suggesting the opposite of what I'm thinking though, then I put Transition & Animation first because it allows you to do something new, whereas Reusability & Composition just allow you to build the same kinds of apps and components, just organized or optimized differently. Does that make sense?

why Single File Components page is under tooling. Wouldn't it fit better in the Components category?

Because they're not actually a feature of Vue core, but of vue-loader/vueify/etc. They're not possible without build tools.

a small screenshot of DevTools in action would also look nice

I actually experimented with adding a screenshot there, but I worried that it took up too much vertical space. Once people have the devtools, I'd like it to be easy to skip over this section to the actual installing of Vue. Once people click through, they'll see a nice screenshot. 🙂

the key section to note that it's required when iterating components?

We do currently have it stand out in a version note and users also receive a warning in the console when using the dev build, so I feel like we might have this well-covered already.

I'd also like to have a warning in the array caveats section, just to draw attention.

This is something a lot of people have missed in the past, because it was below the section about components that we encouraged people to skip. 😅 My hope now is that with the reordering of this page, many more people will see it.

It is important though, so if we still notice a problem with new users, this is a measure I'll consider. I'm just not sure which part we'd turn into a warning, as the entire section is really a sort of warning - and hopefully, the fact that "Caveats" exists in the title will draw attention to it.

hootlex · 2017-08-22T10:03:05Z

@chrisvfritz it seems that you have thought everything 😄

Regarding the "Animations & Transitions", I wanted to say the opposite. Hadn't thought of it this way. It makes sense to show more features before diving into specific needs. 👍🏻

About "Array Caveats", hopefully, people will notice it with the new order. Otherwise, it's hard to decide in which part to emphasize. It's like the whole section should be a warning.

chrisvfritz · 2017-08-28T14:08:00Z

We got a couple reviews, so I'm going ahead and merging this. I at least feel confident there's nothing disasterous here. 😄

cwill · 2017-08-29T06:00:47Z

Just weighing in, spreading info about reactivity throughout the guide as it's relevant seems pretty helpful, but I've found the 'Reactivity In Depth' page an extremely useful reference, especially when working with vuex mutations & dealing with some harder-to-diagnose bugs resulting from setting fields incorrectly. It'd be nice if a consolidated summary of this behavior could stick around somewhere - I needed to reference it today and had to pull it up from archive.

chrisvfritz · 2017-08-31T03:55:29Z

@cwill The page is also still here in source, partially rewritten. The plan is to expand it into a Contributor's Guide that's even more detailed than the current document.

As for the use cases you're thinking of, if the information isn't easily searchable either here or in the Vuex docs, opening an issue would be very welcome. In the API doc in particular, we've been adding more of these kinds of warnings.

cwill · 2017-08-31T04:08:34Z

Ah, adding the relevant warnings to the API docs mostly covers the cases I was concerned about -- I'll keep an eye out :)

chrisvfritz · 2017-08-31T04:27:24Z

@cwill Thanks! 😄

yyx990803 · 2017-09-01T15:01:21Z

Maybe a bit late, but I still think the Reactivity Page should be preserved somewhere, especially for those who wish to have a go-to place when they need to point co-workers to a "source" where explains the whole thing in one place.

I'm thinking maybe we should one extra section titled "Advanced / Internals" that hosts the reactivity chapter and the render function chapter, as both of these somewhat relies on knowledge of how Vue actually works under the hood. IMO these are not only valuable for contributors but also for normal users.

rpkilby · 2017-09-01T15:43:09Z

As a normal user, the reactivity docs have been invaluable in the past. Definitely agree that they should live in a separate section.

chrisvfritz · 2017-09-01T18:48:30Z

@yyx990803 Sounds good! I'll have it back up in a new section soon.

* Reorganize sidebar and some content; cannibalize reactivity page (vuejs#1086) * reorganize sidebar and some content; cannibalize reactivity page * Fix typo in instance.md * Fix typo in instance.md * Change errorMessage: null to error: null in instance.md * Fix typo in reactivity.md.hidden * remove redundant note about filters # Conflicts: # src/v2/api/index.md # src/v2/guide/deployment.md # src/v2/guide/events.md # src/v2/guide/forms.md # src/v2/guide/installation.md # src/v2/guide/instance.md # src/v2/guide/list.md # src/v2/guide/migration-vue-router.md # src/v2/guide/reactivity.md.hidden # src/v2/guide/render-function.md # src/v2/guide/syntax.md # src/v2/guide/transitioning-state.md # src/v2/guide/transitions.md # themes/vue/layout/partials/toc.ejs * Update date * Fix lint

reorganize sidebar and some content; cannibalize reactivity page

909907b

chrisvfritz requested review from yyx990803 and LinusBorg August 18, 2017 21:59

phanan requested changes Aug 19, 2017

View reviewed changes

AllanOcelot mentioned this pull request Aug 20, 2017

Suggest to add a HTML div tag #1080

Closed

chrisvfritz added 4 commits August 20, 2017 12:05

Fix typo in instance.md

5af508e

Fix typo in instance.md

8b541df

Change errorMessage: null to error: null in instance.md

162ab58

Fix typo in reactivity.md.hidden

2d758e5

hootlex reviewed Aug 21, 2017

View reviewed changes

remove redundant note about filters

6323997

chrisvfritz merged commit 2355fbc into master Aug 28, 2017

chrisvfritz deleted the sidebar-reorg branch August 31, 2017 04:27

rpkilby mentioned this pull request Sep 1, 2017

Move reactivity & render function docs into "Advanced / Internals" section #1101

Closed

Reorganize sidebar and some content; cannibalize reactivity page #1086

Reorganize sidebar and some content; cannibalize reactivity page #1086

Uh oh!

Conversation

chrisvfritz commented Aug 18, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Questions

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisvfritz commented Aug 20, 2017

Uh oh!

hootlex left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisvfritz commented Aug 21, 2017

Uh oh!

hootlex commented Aug 22, 2017

Uh oh!

chrisvfritz commented Aug 28, 2017

Uh oh!

cwill commented Aug 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisvfritz commented Aug 31, 2017

Uh oh!

cwill commented Aug 31, 2017

Uh oh!

chrisvfritz commented Aug 31, 2017

Uh oh!

yyx990803 commented Sep 1, 2017

Uh oh!

rpkilby commented Sep 1, 2017

Uh oh!

chrisvfritz commented Sep 1, 2017

Uh oh!

Uh oh!

chrisvfritz commented Aug 18, 2017 •

edited

Loading

cwill commented Aug 29, 2017 •

edited

Loading