Skip to content

Commit

Permalink
Reduce instances of words that shouldn't be used in educational writi…
Browse files Browse the repository at this point in the history
…ng. (#1126)

* Reduce comma use, make language more direct in Unit testing docs

- Some of these commas aren't grammatically correct. Easy fix.
- Over reliance on words that weaken (might, though, may) make a statement
  ambiguous. Remove some to make concepts more direct and understandable.

* Reduce just,simply,obviously,easy, in unit-testing.md

- Remove 'just', 'all you have to', etc.
- Use direct language, reduce word count

* Reduce just,simply,obviously,easy, in common-gotchas.md

* Reduce just,simply,obviously,easy in v2/api/index.md

There are some places where just and simple are valid! So still some instances
in here.

* Reduce just,simply,obviously,easy in adding-instance-properties.md

* Reduce just,simply,obviously,easy in README.md

* Remove a just in class-and-style.md

* Reduce just,simply,obviously,easy in comparison.md

I didn't want to touch this one too much because it's so important to the
adoption of Vue.

* Reduce just,simply,obviously,easy in components.md

* Reduce just,simply,obviously,easy in computed.md

* Reduce just,simply,obviously,easy in conditional.md

* Reduce just,simply,obviously,easy in custom-directive.md

* Reduce just,simply,obviously,easy in events.md

* Reduce just,simply,obviously,easy in forms.md

* Reduce just,simply,obviously,easy in guide/index.md

Some of these are good usages, and I even added an "easy" :). But I think the
removals make the language flow better.

* Reduce just,simply,obviously,easy in instance.md

* Reduce just,simply,obviously,easy in join.md

* Reduce just,simply,obviously,easy in list.md

* Reduce just,simply,obviously,easy in migration-vue-router.md

* Reduce just,simply,obviously,easy in migration-vuex.md

* Reduce just,simply,obviously,easy in migration.md

* Reduce just,simply,obviously,easy in mixins.md

* Reduce just,simply,obviously,easy in reactivity.md

* Reduce just,simply,obviously,easy in render-function.md

* Reduce just,simply,obviously,easy in routing.md

* Reduce just,simply,obviously,easy in single-file-components.md

* Reduce just,simply,obviously,easy in state-management.md

* Reduce just,simply,obviously,easy in transitioning-state.md

* Reduce just,simply,obviously,easy in transitions.md
  • Loading branch information
robwierzbowski authored and chrisvfritz committed Sep 27, 2017
1 parent 2644e02 commit fe98cbe
Show file tree
Hide file tree
Showing 28 changed files with 172 additions and 172 deletions.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ Russian translation is maintained by Translation Gang.

### Want to help with the translation?

If you feel okay with translating sorta alone, just fork the repo, create a "work-in-progress" issue to inform others that you're doing the translation, and just go on.
If you feel okay with translating sorta alone, you can fork the repo, create a "work-in-progress" issue to inform others that you're doing the translation, and go for it.

If you are more of a team player, maybe Translation Gang is for you? Then just let us know somehow that you're ready to join this international open-source translators community. Feel free to contact [Grigoriy Beziuk](https://gbezyuk.github.io) or anybody else from [the team](https://github.com/orgs/translation-gang/people).
If you are more of a team player, Translation Gang might be for you. Let us know somehow that you're ready to join this international open-source translators community. Feel free to contact [Grigoriy Beziuk](https://gbezyuk.github.io) or anybody else from [the team](https://github.com/orgs/translation-gang/people).

And thank you in advance ;)
4 changes: 2 additions & 2 deletions src/_posts/common-gotchas.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Most of the time, when you change a Vue instance's data, the view updates. But t

1. When you are **adding a new property** that wasn't present when the data was observed. Due to the limitation of ES5 and to ensure consistent behavior across browsers, Vue.js cannot detect property addition/deletions. The best practice is to always declare properties that need to be reactive upfront. In cases where you absolutely need to add or delete properties at runtime, use the global [`Vue.set`](/api/#Vue-set) or [`Vue.delete`](/api/#Vue-delete) methods.

2. When you modify an Array by directly setting an index (e.g. `arr[0] = val`) or modifying its `length` property. Similarly, Vue.js cannot pickup these changes. Always modify arrays by using an Array instance method, or replacing it entirely. Vue provides a convenience method `arr.$set(index, value)` which is just syntax sugar for `arr.splice(index, 1, value)`.
2. When you modify an Array by directly setting an index (e.g. `arr[0] = val`) or modifying its `length` property. Similarly, Vue.js cannot pickup these changes. Always modify arrays by using an Array instance method, or replacing it entirely. Vue provides a convenience method `arr.$set(index, value)` which is syntax sugar for `arr.splice(index, 1, value)`.

Further reading: [Reactivity in Depth](/guide/reactivity.html) and [Array Change Detection](http://vuejs.org/guide/list.html#Array-Change-Detection).

Expand All @@ -25,7 +25,7 @@ Further reading: [Async Update Queue](/guide/reactivity.html#Async-Update-Queue)

### Why does `data` need to be a function?

In the basic examples, we declare the `data` directly as a plain object. This is because we are creating only a single instance with `new Vue()`. However, when defining a **component**, `data` must be declared as a function that returns the initial data object. Why? Because there will be many instances created using the same definition. If we still use a plain object for `data`, that same object will be **shared by reference** across all instance created! By providing a `data` function, every time a new instance is created, we can simply call it to return a fresh copy of the initial data.
In the basic examples, we declare the `data` directly as a plain object. This is because we are creating only a single instance with `new Vue()`. However, when defining a **component**, `data` must be declared as a function that returns the initial data object. Why? Because there will be many instances created using the same definition. If we still use a plain object for `data`, that same object will be **shared by reference** across all instance created! By providing a `data` function, every time a new instance is created we can call it to return a fresh copy of the initial data.

Further reading: [Component Option Caveats](/guide/components.html#Component-Option-Caveats).

Expand Down
26 changes: 13 additions & 13 deletions src/v2/api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -286,7 +286,7 @@ type: api
unbind: function () {}
})

// register (simple function directive)
// register (function directive)
Vue.directive('my-directive', function () {
// this will be called as `bind` and `update`
})
Expand Down Expand Up @@ -415,15 +415,15 @@ type: api
- **Details:**
The data object for the Vue instance. Vue will recursively convert its properties into getter/setters to make it "reactive". **The object must be plain**: native objects such as browser API objects and prototype properties are ignored. A rule of thumb is that data should just be data - it is not recommended to observe objects with its own stateful behavior.
The data object for the Vue instance. Vue will recursively convert its properties into getter/setters to make it "reactive". **The object must be plain**: native objects such as browser API objects and prototype properties are ignored. A rule of thumb is that data should just be data - it is not recommended to observe objects with their own stateful behavior.
Once observed, you can no longer add reactive properties to the root data object. It is therefore recommended to declare all root-level reactive properties upfront, before creating the instance.
After the instance is created, the original data object can be accessed as `vm.$data`. The Vue instance also proxies all the properties found on the data object, so `vm.a` will be equivalent to `vm.$data.a`.
Properties that start with `_` or `$` will **not** be proxied on the Vue instance because they may conflict with Vue's internal properties and API methods. You will have to access them as `vm.$data._property`.
When defining a **component**, `data` must be declared as a function that returns the initial data object, because there will be many instances created using the same definition. If we still use a plain object for `data`, that same object will be **shared by reference** across all instances created! By providing a `data` function, every time a new instance is created, we can simply call it to return a fresh copy of the initial data.
When defining a **component**, `data` must be declared as a function that returns the initial data object, because there will be many instances created using the same definition. If we use a plain object for `data`, that same object will be **shared by reference** across all instances created! By providing a `data` function, every time a new instance is created we can call it to return a fresh copy of the initial data.
If required, a deep clone of the original object can be obtained by passing `vm.$data` through `JSON.parse(JSON.stringify(...))`.
Expand Down Expand Up @@ -457,7 +457,7 @@ type: api
- **Details:**
A list/hash of attributes that are exposed to accept data from the parent component. It has a simple Array-based syntax and an alternative Object-based syntax that allows advanced configurations such as type checking, custom validation and default values.
A list/hash of attributes that are exposed to accept data from the parent component. It has an Array-based simple syntax and an alternative Object-based syntax that allows advanced configurations such as type checking, custom validation and default values.
- **Example:**
Expand All @@ -470,7 +470,7 @@ type: api
// object syntax with validation
Vue.component('props-demo-advanced', {
props: {
// just type check
// type check
height: Number,
// type check plus other validations
age: {
Expand Down Expand Up @@ -530,7 +530,7 @@ type: api
var vm = new Vue({
data: { a: 1 },
computed: {
// get only, just need a function
// get only
aDouble: function () {
return this.a * 2
},
Expand Down Expand Up @@ -710,7 +710,7 @@ type: api
- **Details:**
Called synchronously after the instance has just been initialized, before data observation and event/watcher setup.
Called synchronously immediately after the instance has been initialized, before data observation and event/watcher setup.
- **See also:** [Lifecycle Diagram](../guide/instance.html#Lifecycle-Diagram)
Expand Down Expand Up @@ -742,7 +742,7 @@ type: api
- **Details:**
Called after the instance has just been mounted where `el` is replaced by the newly created `vm.$el`. If the root instance is mounted to an in-document element, `vm.$el` will also be in-document when `mounted` is called.
Called after the instance has been mounted, where `el` is replaced by the newly created `vm.$el`. If the root instance is mounted to an in-document element, `vm.$el` will also be in-document when `mounted` is called.
Note that `mounted` does **not** guarantee that all child components have also been mounted. If you want to wait until the entire view has been rendered, you can use [vm.$nextTick](#vm-nextTick) inside of `mounted`:
Expand Down Expand Up @@ -900,7 +900,7 @@ type: api
- **Details:**
The `mixins` option accepts an array of mixin objects. These mixin objects can contain instance options just like normal instance objects, and they will be merged against the eventual options using the same option merging logic in `Vue.extend()`. e.g. If your mixin contains a created hook and the component itself also has one, both functions will be called.
The `mixins` option accepts an array of mixin objects. These mixin objects can contain instance options like normal instance objects, and they will be merged against the eventual options using the same option merging logic in `Vue.extend()`. e.g. If your mixin contains a created hook and the component itself also has one, both functions will be called.
Mixin hooks are called in the order they are provided, and called before the component's own hooks.
Expand Down Expand Up @@ -1069,7 +1069,7 @@ type: api
- **Details:**
Causes a component to be stateless (no `data`) and instanceless (no `this` context). They are simply a `render` function that returns virtual nodes making them much cheaper to render.
Causes a component to be stateless (no `data`) and instanceless (no `this` context). They are only a `render` function that returns virtual nodes making them much cheaper to render.
- **See also:** [Functional Components](../guide/render-function.html#Functional-Components)
Expand Down Expand Up @@ -1357,7 +1357,7 @@ type: api
- **Usage:**
Watch an expression or a computed function on the Vue instance for changes. The callback gets called with the new value and the old value. The expression only accepts simple dot-delimited paths. For more complex expression, use a function instead.
Watch an expression or a computed function on the Vue instance for changes. The callback gets called with the new value and the old value. The expression only accepts dot-delimited paths. For more complex expressions, use a function instead.
<p class="tip">Note: when mutating (rather than replacing) an Object or an Array, the old value will be the same as new value because they reference the same Object/Array. Vue doesn't keep a copy of the pre-mutate value.</p>
Expand Down Expand Up @@ -1763,7 +1763,7 @@ type: api

- **Usage:**

Attaches an event listener to the element. The event type is denoted by the argument. The expression can either be a method name or an inline statement, or simply omitted when there are modifiers present.
Attaches an event listener to the element. The event type is denoted by the argument. The expression can be a method name, an inline statement, or omitted if there are modifiers present.

Starting in 2.4.0+, `v-on` also supports binding to an object of event/listener pairs without an argument. Note when using the object syntax, it does not support any modifiers.

Expand Down Expand Up @@ -2131,7 +2131,7 @@ type: api

- **Usage:**

`<transition>` serve as transition effects for **single** element/component. The `<transition>` does not render an extra DOM element, nor does it show up in the inspected component hierarchy. It simply applies the transition behavior to the wrapped content inside.
`<transition>` serve as transition effects for **single** element/component. The `<transition>` only applies the transition behavior to the wrapped content inside; it doesn't render an extra DOM element, or show up in the inspected component hierarchy.

```html
<!-- simple element -->
Expand Down
12 changes: 6 additions & 6 deletions src/v2/cookbook/adding-instance-properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,19 @@ new Vue({
})
```

Then `"My App"` will be logged to the console. It's that simple!
Then `"My App"` will be logged to the console!

## The Importance of Scoping Instance Properties

You may be wondering:

> "Why does `appName` start with `$`? Is that important? What does it do?
No magic is happening here. `$` is simply a convention Vue uses for properties that are available to all instances. This avoids conflicts with any defined data, computed properties, or methods.
No magic is happening here. `$` is a convention Vue uses for properties that are available to all instances. This avoids conflicts with any defined data, computed properties, or methods.

> "Conflicts? What do you mean?"
Another great question! If you just set:
Another great question! If you set:

``` js
Vue.prototype.appName = 'My App'
Expand All @@ -46,7 +46,7 @@ Then what would you expect to be logged below?
new Vue({
data: {
// Uh oh - appName is *also* the name of the
// instance property we just defined!
// instance property we defined!
appName: 'The name of some other app'
},
beforeCreate: function () {
Expand Down Expand Up @@ -143,7 +143,7 @@ As long as you're vigilant in scoping prototype properties, using this pattern i

However, it can sometimes cause confusion with other developers. They might see `this.$http`, for example, and think, "Oh, I didn't know about this Vue feature!" Then they move to a different project and are confused when `this.$http` is undefined. Or, maybe they want to Google how to do something, but can't find results because they don't realize they're actually using Axios under an alias.

__The convenience comes at the cost of explicitness.__ When just looking at a component, it's impossible to tell where `$http` came from. Vue itself? A plugin? A coworker?
__The convenience comes at the cost of explicitness.__ When looking at a component, it's impossible to tell where `$http` came from. Vue itself? A plugin? A coworker?

So what are the alternatives?

Expand Down Expand Up @@ -171,7 +171,7 @@ var App = Object.freeze({

<p class="tip">If you raised an eyebrow at `Object.freeze`, what it does is prevent the object from being changed in the future. This essentially makes all its properties constants, protecting you from future state bugs.</p>

Now the source of these shared properties is much more obvious: there's an `App` object defined somewhere in the app. To find it, developers need only run a project-wide search.
Now the source of these shared properties is more obvious: there's an `App` object defined somewhere in the app. To find it, developers can run a project-wide search.

Another advantage is that `App` can now be used _anywhere_ in your code, whether it's Vue-related or not. That includes attaching values directly to instance options, rather than having to enter a function to access properties on `this`:

Expand Down
2 changes: 1 addition & 1 deletion src/v2/guide/class-and-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ type: guide
order: 6
---

A common need for data binding is manipulating an element's class list and its inline styles. Since they are both attributes, we can use `v-bind` to handle them: we just need to calculate a final string with our expressions. However, meddling with string concatenation is annoying and error-prone. For this reason, Vue provides special enhancements when `v-bind` is used with `class` and `style`. In addition to strings, the expressions can also evaluate to objects or arrays.
A common need for data binding is manipulating an element's class list and its inline styles. Since they are both attributes, we can use `v-bind` to handle them: we only need to calculate a final string with our expressions. However, meddling with string concatenation is annoying and error-prone. For this reason, Vue provides special enhancements when `v-bind` is used with `class` and `style`. In addition to strings, the expressions can also evaluate to objects or arrays.

## Binding HTML Classes

Expand Down
Loading

0 comments on commit fe98cbe

Please sign in to comment.