doc: replace uses of `you` and other style nits #12673

jasnell · 2017-04-26T17:17:51Z

Replace uses of the pronouns you and your throughout the docs + other minor style nits

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

vsemozhetbyt · 2017-04-26T17:27:40Z

doc/api/cluster.md

@@ -713,8 +713,8 @@ added: v0.11.2

 The scheduling policy, either `cluster.SCHED_RR` for round-robin or
 `cluster.SCHED_NONE` to leave it to the operating system. This is a
-global setting and effectively frozen once you spawn the first worker
-or call `cluster.setupMaster()`, whatever comes first.
+global setting and effectively frozen once wither the first worker is spawned,


wither -> either?

heh... yes, is should be either

vsemozhetbyt · 2017-04-26T18:14:58Z

doc/api/globals.md

+In browsers, the top-level scope is the global scope. This means that
+`var something`, within the browser, will define a new global variable. In
+Node.js this is different. The top-level scope is not the global scope;
+`var something` inside an Node.js module will be local to that module.


an Node.js -> a Node.js?

vsemozhetbyt · 2017-04-26T18:19:29Z

doc/api/modules.md

-may itself have dependencies, and in some cases, these dependencies may even
-collide or form cycles.
+Packages can depend on one another. In order to install package `foo`, it
+may be necessary to install a specific version of package `bar`.  The `bar`


Two spaces in succession.

gibfahn

Some nits (most of them from the existing docs, but while you're there)

gibfahn · 2017-04-28T08:18:52Z

doc/api/cluster.md

-responsibility to manage the worker pool for your application's needs.
+will be dropped and new connections will be refused. Node.js does not
+automatically manage the number of workers, however. It is the application's
+responsibility to manage the worker pool based on it's own needs.


it's -> its

gibfahn · 2017-04-28T08:19:49Z

doc/api/cluster.md

-created. It is disconnected after the `'disconnect'` event is emitted.
+This function returns `true` if the worker is connected to its master via its
+IPC channel, `false` otherwise. A worker is connected to its master after it's
+been created. It is disconnected after the `'disconnect'` event is emitted.


it's been -> it has been

gibfahn · 2017-04-28T08:21:59Z

doc/api/cluster.md

-The boolean `worker.exitedAfterDisconnect` lets you distinguish between voluntary
-and accidental exit, the master may choose not to respawn a worker based on
-this value.
+The boolean `worker.exitedAfterDisconnect` allows distinguishing between


allows distinguishs -> is used to distinguish

allows suggests that's just one of the things it can do right?

gibfahn · 2017-04-28T08:22:10Z

doc/api/cluster.md

@@ -469,7 +467,7 @@ An alias to [`worker.exitedAfterDisconnect`][].

 Set by calling `.kill()` or `.disconnect()`. Until then, it is `undefined`.

-The boolean `worker.suicide` lets you distinguish between voluntary
+The boolean `worker.suicide` allows distinguishs between voluntary


allows distinguishs -> is used to distinguish

as above...

gibfahn · 2017-04-28T08:23:45Z

doc/api/cluster.md

-After calling `listen()` from a worker, when the `'listening'` event is emitted on
-the server, a `'listening'` event will also be emitted on `cluster` in the master.
+After calling `listen()` from a worker, when the `'listening'` event is emitted
+on the server, a `'listening'` event will also be emitted on `cluster` in the


server, a -> server a

I think that's easier to parse, happy to be disagreed with though.

gibfahn · 2017-04-28T09:39:47Z

doc/api/modules.md

@@ -203,8 +200,8 @@ executed multiple times.  This is an important feature.  With it,
 "partially done" objects can be returned, thus allowing transitive
 dependencies to be loaded even when they would cause cycles.

-If you want to have a module execute code multiple times, then export a
-function, and call that function.
+To have a module execute code multiple times, then export a function, and call


gibfahn · 2017-04-28T09:41:52Z

doc/api/modules.md

@@ -297,8 +294,8 @@ a done
 in main, a.done=true, b.done=true
 ```

-If you have cyclic module dependencies in your program, make sure to
-plan accordingly.
+Careful planning is required to allow cyclic module dependencies within an


to allow cyclic module dependencies to what? The sentence as is suggests that they won't be allowed unless you plan carefully, but AIUI what will happen is that the application just won't work correctly.

Maybe:

to allow cyclic module dependencies to work correctly within an application.

gibfahn · 2017-04-28T09:45:48Z

doc/api/modules.md

+These are mostly for historic reasons.
+
+*Note*: It is strongly encouraged to place dependencies locally in
+`node_modules` folders. These will be loaded faster, and more reliably.


Maybe locally in node_modules folders -> in the local node_modules folder

gibfahn · 2017-04-28T09:47:20Z

doc/api/repl.md

@@ -499,9 +499,9 @@ by the `NODE_REPL_HISTORY` variable, as documented in the

 For advanced line-editors, start Node.js with the environmental variable
 `NODE_NO_READLINE=1`. This will start the main and debugger REPL in canonical
-terminal settings which will allow you to use with `rlwrap`.
+terminal settings which will allow use with `rlwrap`.


Maybe settings which -> settings, which

gibfahn · 2017-04-28T09:50:54Z

doc/api/net.md

@@ -650,7 +650,7 @@ added: v0.9.6
 -->

 The string representation of the local IP address the remote client is
-connecting on. For example, if you are listening on `'0.0.0.0'` and the
+connecting on. For example, when listening on `'0.0.0.0'` and the


I don't think when...and works here. Can we be more specific about what is listening on '0.0.0.0'?

Sorry for not giving a concrete suggestion, I can't think of a good way to say this.

Replace uses of the pronouns `you` and `your` throughout the docs + other minor style nits

jasnell · 2017-04-28T12:46:03Z

@gibfahn ... updated!

gibfahn

Thanks, LGTM. Especially impressed by how you fixed the bits where I basically said "this is bad, I have no constructive suggestions, please make better..."

Replace uses of the pronouns `you` and `your` throughout the docs + other minor style nits PR-URL: #12673 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]>

jasnell · 2017-04-28T14:59:51Z

Landed in 71f22c8

gibfahn · 2017-06-18T22:39:08Z

Should this be backported to v6.x-staging? If yes please follow the guide and raise a backport PR, if no let me know or add the dont-land-on label.

This looks reasonably easy to backport.

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 26, 2017

vsemozhetbyt reviewed Apr 26, 2017

View reviewed changes

jasnell force-pushed the i-banish-you-from-the-docs branch from d801879 to 3213cfd Compare April 26, 2017 17:38

vsemozhetbyt reviewed Apr 26, 2017

View reviewed changes

vsemozhetbyt approved these changes Apr 26, 2017

View reviewed changes

benjamingr approved these changes Apr 26, 2017

View reviewed changes

lpinca approved these changes Apr 27, 2017

View reviewed changes

cjihrig approved these changes Apr 27, 2017

View reviewed changes

gibfahn suggested changes Apr 28, 2017

View reviewed changes

jasnell added 2 commits April 28, 2017 05:32

doc: replace uses of you and other style nits

ea3efc6

Replace uses of the pronouns `you` and `your` throughout the docs + other minor style nits

Address feedback

83acb55

jasnell force-pushed the i-banish-you-from-the-docs branch from 3213cfd to 83acb55 Compare April 28, 2017 12:45

gibfahn approved these changes Apr 28, 2017

View reviewed changes

jasnell closed this Apr 28, 2017

jasnell mentioned this pull request May 11, 2017

8.0.0 Release Proposal #12220

Closed

gibfahn mentioned this pull request Jun 15, 2017

Auditing for 6.11.1 nodejs/Release#230

Closed

3 tasks

gibfahn added the backport-requested-v6.x label Jun 18, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: replace uses of `you` and other style nits #12673

doc: replace uses of `you` and other style nits #12673

jasnell commented Apr 26, 2017

vsemozhetbyt Apr 26, 2017

jasnell Apr 26, 2017

vsemozhetbyt Apr 26, 2017

vsemozhetbyt Apr 26, 2017

gibfahn left a comment

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

gibfahn Apr 28, 2017

jasnell commented Apr 28, 2017

gibfahn left a comment

jasnell commented Apr 28, 2017

gibfahn commented Jun 18, 2017

doc: replace uses of you and other style nits #12673

doc: replace uses of you and other style nits #12673

Conversation

jasnell commented Apr 26, 2017

Checklist

Affected core subsystem(s)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gibfahn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Apr 28, 2017

gibfahn left a comment

Choose a reason for hiding this comment

jasnell commented Apr 28, 2017

gibfahn commented Jun 18, 2017

doc: replace uses of `you` and other style nits #12673

doc: replace uses of `you` and other style nits #12673