Reduce instances of words that shouldn't be used in educational writing. #1126

robwierzbowski · 2017-09-12T15:59:30Z

I tried not to revise too much, mostly removing instances of just, simply, obviously, easily. In most cases this made the language more direct and concrete, which I think aides understanding.

There are places where these words are useful, so this isn't a 100% find/replace/delete. I used my judgement — comments are welcome.

Around half of the removals relate to my original issue (don't assume ease), and the other half improve the flow of reading by removing words when they're unnecessary for understanding.

I avoided revising any blog posts, except common-gotchas which I thought might still get a lot of views.

- 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.

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

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

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

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

robwierzbowski · 2017-09-12T16:11:44Z

src/v2/guide/join.md

-
-I hope that right now, you're reading this sentence in your preferred language. If not, would you like to help us get there?
-
-If so, please feel free to fork the repo for [these docs](https://github.com/vuejs/vuejs.org/) or for any other officially maintained documentation, then start translating. Once you've made some progress, open an issue or pull request in the main repo and we'll put out a call for more contributors to help you out.


Not sure why this is a whole file diff. I removed a single just.

Maybe windows vs unix line endings?

rpkilby

Hi. Just my two cents, but there seem to be a few cases that remove helpful context. I've only quoted a couple of examples and haven't reviewed this extensively.

rpkilby · 2017-09-12T18:05:32Z

src/v2/cookbook/adding-instance-properties.md

@@ -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!


"just" implies proximity, rather than conceptual simplicity

It does. I think the "recently" is implied, but happy to revert.

I definitely made some judgement calls, so comments welcome.

rpkilby · 2017-09-12T18:05:50Z

src/v2/api/index.md

@@ -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.


"simple" emphasizes the lack of complexity of the expression, rather than conceptual simplicity

IMO it's superfluous, and reads more simply (ha!) without it.

robwierzbowski · 2017-09-12T18:24:33Z

Thanks for starting a review @rpkilby. Happy to revert anything, or continue revisions. Just to be clear, I did remove more than just conceptual simplicity instances of these words, noted in the PR description.

rpkilby · 2017-09-12T18:34:53Z

Yep, just demonstrating a couple of the places where the removed words were not referencing conceptual accessibility/simplicity.

Either way, +1 on the changes. It's kind of interesting - never really thought about this before.

chrisvfritz · 2017-09-13T04:41:14Z

Thank you @robwierzbowski! It might take me a few days to review with my schedule this week, but I'm really looking forward to it. 😄

znck · 2017-09-13T06:20:28Z

👍 Nice work @robwierzbowski.

codebryo · 2017-09-13T16:29:07Z

Wow, cool PR. Thanks for that. <3

chrisvfritz · 2017-09-21T15:12:04Z

@robwierzbowski Sorry it took me a bit longer to get through this! I didn't see anything that wasn't at least neutral to me and most were definite improvements. 😄 Thanks again and I look forward to more PRs in the future!

robwierzbowski · 2017-09-21T15:22:00Z

Thanks! I might submit a PR with some potential simplifications I noted while writing this one.

I'm trying to get some projects I'm involved with on Vue, and I think the current documentation (and culture of writing docs) is a huge plus. Happy to give back.

…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

rpkilby · 2017-11-09T18:10:42Z

Hi @robwierzbowski - out of curiosity, did you use any linting tools for this PR, or did you do this by hand?

robwierzbowski · 2017-11-09T18:37:24Z

@rpkilby Just find and replace 🙂

robwierzbowski · 2017-11-09T18:38:38Z

I️ also read over pretty much every line in the documentation. So, find and replace +

rpkilby · 2017-11-09T19:42:09Z

Thanks. I also just noticed the article you originally referenced.

robwierzbowski added 29 commits September 12, 2017 12:08

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

2d1da92

- 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

e2a8aca

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

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

bb34256

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

a4ba1f2

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

2370313

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

f38cb71

Remove a just in class-and-style.md

423616f

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

c5336b2

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

033ea04

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

f051502

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

bc7bd37

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

2dad485

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

6e4d24b

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

04ad983

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

77a3174

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

9e3cb49

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

381da73

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

547cd49

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

c327986

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

081a003

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

f74a67b

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

8964f2a

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

858024f

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

976308e

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

f0e99c7

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

f8f0fdd

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

de21684

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

0547bd4

Reduce just,simply,obviously,easy in transitions.md

0aa0c61

robwierzbowski commented Sep 12, 2017

View reviewed changes

rpkilby reviewed Sep 12, 2017

View reviewed changes

chrisvfritz added 2 commits September 21, 2017 11:09

Merge branch 'master' into slightly-less-obvious

8a84294

Merge branch 'master' into slightly-less-obvious

95d9e85

chrisvfritz merged commit fe25553 into vuejs:master Sep 21, 2017

robwierzbowski deleted the slightly-less-obvious branch November 9, 2017 18:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reduce instances of words that shouldn't be used in educational writing. #1126

Reduce instances of words that shouldn't be used in educational writing. #1126

robwierzbowski commented Sep 12, 2017 •

edited

Loading

robwierzbowski Sep 12, 2017

rpkilby Sep 12, 2017

rpkilby left a comment

rpkilby Sep 12, 2017

robwierzbowski Sep 12, 2017

rpkilby Sep 12, 2017

robwierzbowski Sep 12, 2017

robwierzbowski commented Sep 12, 2017

rpkilby commented Sep 12, 2017

chrisvfritz commented Sep 13, 2017

znck commented Sep 13, 2017

codebryo commented Sep 13, 2017

chrisvfritz commented Sep 21, 2017

robwierzbowski commented Sep 21, 2017 •

edited

Loading

rpkilby commented Nov 9, 2017

robwierzbowski commented Nov 9, 2017

robwierzbowski commented Nov 9, 2017

rpkilby commented Nov 9, 2017


		I hope that right now, you're reading this sentence in your preferred language. If not, would you like to help us get there?

		If so, please feel free to fork the repo for [these docs](https://github.com/vuejs/vuejs.org/) or for any other officially maintained documentation, then start translating. Once you've made some progress, open an issue or pull request in the main repo and we'll put out a call for more contributors to help you out.

		@@ -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.

Reduce instances of words that shouldn't be used in educational writing. #1126

Reduce instances of words that shouldn't be used in educational writing. #1126

Conversation

robwierzbowski commented Sep 12, 2017 • edited Loading

robwierzbowski Sep 12, 2017

Choose a reason for hiding this comment

rpkilby Sep 12, 2017

Choose a reason for hiding this comment

rpkilby left a comment

Choose a reason for hiding this comment

rpkilby Sep 12, 2017

Choose a reason for hiding this comment

robwierzbowski Sep 12, 2017

Choose a reason for hiding this comment

rpkilby Sep 12, 2017

Choose a reason for hiding this comment

robwierzbowski Sep 12, 2017

Choose a reason for hiding this comment

robwierzbowski commented Sep 12, 2017

rpkilby commented Sep 12, 2017

chrisvfritz commented Sep 13, 2017

znck commented Sep 13, 2017

codebryo commented Sep 13, 2017

chrisvfritz commented Sep 21, 2017

robwierzbowski commented Sep 21, 2017 • edited Loading

rpkilby commented Nov 9, 2017

robwierzbowski commented Nov 9, 2017

robwierzbowski commented Nov 9, 2017

rpkilby commented Nov 9, 2017

robwierzbowski commented Sep 12, 2017 •

edited

Loading

robwierzbowski commented Sep 21, 2017 •

edited

Loading