doc : being more explicit in the synopsis #17977

timotew · 2018-01-04T10:20:21Z

Assuming less knowledge on the part of the reader, making it easier to for starters.

Fixes: #17970, nodejs/help#1049

Checklist

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

Affected core subsystem(s)

fs

Assuming less knowledge on the part of the reader, making it easier to get start using Node.js.

vsemozhetbyt · 2018-01-04T12:28:13Z

doc/api/synopsis.md

+
+Next, create a new source file in the `projects` folder and call it `hello_world.js`.
+
+If you’re using more than one word in your filename, use an underscore(`_`) to separate them for simplicity and avoid using the space character in file names. 


Maybe "use an underscore (_) or a hyphen (-)"? Some style guides and practices (including Node.js repository) prefer hyphens, so we can mention both here.

vsemozhetbyt · 2018-01-04T12:29:53Z

doc/api/synopsis.md

-`'Hello World'`:
+`'Hello World!'`:
+
+Firstly, Make sure you have downloaded Node.js from [Node.js Official website](http://nodejs.org/#download).


Make -> make?

vsemozhetbyt · 2018-01-04T12:30:36Z

doc/api/synopsis.md

+`'Hello World!'`:
+
+Firstly, Make sure you have downloaded Node.js from [Node.js Official website](http://nodejs.org/#download).
+Then, Follow this [installation guide](https://nodejs.org/en/download/package-manager/).


Follow -> follow?

vsemozhetbyt · 2018-01-04T12:30:59Z

doc/api/synopsis.md

+Then, Follow this [installation guide](https://nodejs.org/en/download/package-manager/).
+
+
+Now, Create an empty project folder called `projects`, navigate into it:


Create -> create?

vsemozhetbyt · 2018-01-04T12:33:09Z

doc/api/synopsis.md

+
+If you’re using more than one word in your filename, use an underscore(`_`) to separate them for simplicity and avoid using the space character in file names. 
+
+For example, you’d use `hello_world.js` rather than `hello world.js`.


We usually do not use personal pronouns in the docs, but this guide is a less formal one, so I am not sure if this is OK. Let's see what others think.

vsemozhetbyt · 2018-01-04T12:34:03Z

doc/api/synopsis.md

+For example, you’d use `hello_world.js` rather than `hello world.js`.
+Node.js files always end with the `.js` extension. 
+
+open `hello_world.js` in your favorite text editor and paste in the following content.


open -> Open?

vsemozhetbyt · 2018-01-04T12:37:21Z

doc/api/synopsis.md

-
-To run the server, put the code into a file called `example.js` and execute
-it with Node.js:
+Save the file, and go back to your terminal window enter the following command:


Save the file, go back to your terminal window and enter?

vsemozhetbyt · 2018-01-04T12:38:33Z

doc/api/synopsis.md

 ```
+Your should see an output like this in your terminal to indicate Node.js server is running:


Your -> you? (If pronouns are considered appropriate).

vsemozhetbyt · 2018-01-04T12:39:52Z

doc/api/synopsis.md

+ ```javascript
+ Server running at http://127.0.0.1:3000/
+ ````
+ Now, Open your favorite browser and visit `http://127.0.0.1:3000`.


Open ->open?

vsemozhetbyt

LGTM with some nits, but let's see what native speakers think.

Thank you!

gibfahn · 2018-01-04T13:26:08Z

We usually do not use personal pronouns in the docs, but this guide is a less formal one, so I am not sure if this is OK. Let's see what others think.

I think it's fine here, this is directly addressed to the user "How you can run these code samples".

gibfahn

Mostly looks good

gibfahn · 2018-01-04T10:36:36Z

doc/api/synopsis.md

+`'Hello World!'`:
+
+Firstly, Make sure you have downloaded Node.js from [Node.js Official website](http://nodejs.org/#download).
+Then, Follow this [installation guide](https://nodejs.org/en/download/package-manager/).


Maybe change:

Then, Follow this

to

If you want to install Node using a package manager, see [this guide]

If people are just getting started with Node they probably don't need to know about package managers.

gibfahn · 2018-01-04T10:38:37Z

doc/api/synopsis.md

+Now, Create an empty project folder called `projects`, navigate into it:
+
+Linux and Mac:
+


Can you include something like this:

We’ll be showing off a number of commands using a terminal, and those lines all start with $. You don’t need to type in the $ character; they are there to indicate the start of each command. You’ll see many tutorials and examples around the web that follow this convention: $ for commands run as a regular user, and # for commands you should be running as an administrator. Lines that don’t start with $ are typically showing the output of the previous command.

(taken from https://doc.rust-lang.org/book/second-edition/ch01-01-installation.html#installation, feel free to reword it).

@gibfahn Note my previous comments about personal pronouns. I wonder if this should really be a guide so that we don't have to worry about that sort of thing. Link to it from the docs?

gibfahn · 2018-01-04T13:24:31Z

doc/api/synopsis.md

+Then, Follow this [installation guide](https://nodejs.org/en/download/package-manager/).
+
+
+Now, Create an empty project folder called `projects`, navigate into it:


Can you tweak this to make it clear that projects is just an example name, not one that has any significance (i.e. you don't have to call it projects)

Maybe:

If you aren't sure where to put your code, a good place to start is to create a projects folder in your home directory like so:

(
I took inspiration from the rust book again, specifically here:

First, make a directory to put your Rust code in. Rust doesn’t care where your code lives, but for this book, we’d suggest making a projects directory in your home directory and keeping all your projects there. Open a terminal and enter the following commands to make a directory for this particular project:

https://doc.rust-lang.org/book/second-edition/ch01-02-hello-world.html#creating-a-project-directory
)

gibfahn · 2018-01-04T13:26:40Z

doc/api/synopsis.md

+`'Hello World!'`:
+
+Firstly, make sure you have downloaded Node.js from [Node.js Official website](http://nodejs.org/#download).
+Then, follow this [installation guide](https://nodejs.org/en/download/package-manager/).


Maybe change:

Then, Follow this

to

If you want to install Node using a package manager, see [this guide]

If people are just getting started with Node they probably don't need to know about package managers.

gibfahn · 2018-01-04T13:26:53Z

doc/api/synopsis.md

+Now, create an empty project folder called `projects`, navigate into it:
+
+Linux and Mac:
+


Can you include something like this:

We’ll be showing off a number of commands using a terminal, and those lines all start with $. You don’t need to type in the $ character; they are there to indicate the start of each command. You’ll see many tutorials and examples around the web that follow this convention: $ for commands run as a regular user, and # for commands you should be running as an administrator. Lines that don’t start with $ are typically showing the output of the previous command.

(taken from https://doc.rust-lang.org/book/second-edition/ch01-01-installation.html#installation, feel free to reword it).

gibfahn · 2018-01-04T13:28:21Z

doc/api/synopsis.md

+
+Next, create a new source file in the `projects` folder and call it `hello-world.js`.
+
+If you’re using more than one word in your filename, use an hyphen (`-`) or an underscore(`_`) to separate them for simplicity and avoid using the space character in file names. 


Can you wrap lines at 80 chars?

gibfahn · 2018-01-04T13:28:41Z

doc/api/synopsis.md

 ```
+you should see an output like this in your terminal to indicate Node.js server is running:
+ ```javascript


Maybe remove the javascript here.

gibfahn · 2018-01-04T13:32:12Z

doc/api/synopsis.md

+Then, follow this [installation guide](https://nodejs.org/en/download/package-manager/).
+
+
+Now, create an empty project folder called `projects`, navigate into it:


Can you make it more clear that your folder doesn't have to be called projects? Maybe:

Create a directory to put your code in, for example to create a projects folder in your home directory you can run these commands in a terminal:

gibfahn · 2018-01-04T13:33:29Z

@the-wazz could you let us know whether this is clear for you?

gireeshpunathil · 2018-01-04T13:42:10Z

doc/api/synopsis.md

+
+Now, create an empty project folder called `projects`, navigate into it:
+
+Linux and Mac:


May be UNIX rather than Linux and Mac ?

We usually go with POSIX but people might not know what that means. UNIX is technically incorrect because that refers to a specific trademarked operating system. UNIX-like is often used instead. Maybe Unix/macOS to conform with BUILDING.md even though I don't like that personally. This gets tricky. Maybe leave it as Linux and Mac after all. :-D

doc/api> grep -i "UNIX" * | wc -l 40

We seem to be using UNIX abundantly to refer UNIX-like systems.

If we use Linux and MAC, it leaves an impression of either:

Only Linux and MAC are supported

The example holds good only for Linux and MAC

@gireeshpunathil I'm convinced. Let's go with UNIX (or Unix or UNIX-like) and consolidating terminology/typography across documents can happen some other time. Certainly "Linux and macOS" would explicitly exclude (for example) AIX which certainly is incorrect in this case.

Trott · 2018-01-04T19:30:06Z

doc/api/synopsis.md

+
+they are there to indicate the start of each command. 
+
+You’ll see many tutorials and examples around the web that follow this 


Micro-nit (non-blocking, ignore if you disagree): remove around the web

Trott · 2018-01-04T19:30:54Z

doc/api/synopsis.md

+`'Hello World!'`:
+
+We’ll be displaying a number of commands using a terminal, and those lines 
+


Docs are usually single-spaced. I'm not sure that double-spacing like this will render the same as other docs. Probably best to single-space it. (Blank lines between paragraphs are 👍 though!)

Trott · 2018-01-04T19:36:19Z

I almost feel bad leaving this comment, but since this is a doc and not an informal guide, we try to avoid personal pronouns like you (although I'm sure there are many examples where we don't manage to avoid it). If you can re-word some or all of it, it might fit the tone of other docs better.

For example, instead of:

We’ll be displaying a number of commands using a terminal, and those lines
start with $ or >. You don’t need to type in the $ and > character;
they are there to indicate the start of each command.

...maybe more like this?:

Commands displayed in this document are shown starting with $ or >
to replicate how they would appear in a user's terminal. Do not include the $
or > when running these commands.

Trott · 2018-01-04T19:36:52Z

(By the way, the personal pronoun thing and a bunch of other rules/guidelines can be found at https://github.com/nodejs/node/blob/master/doc/STYLE_GUIDE.md.)

Trott · 2018-01-04T19:39:12Z

doc/api/synopsis.md

+
+and call it `hello-world.js`.
+
+If you’re using more than one word in your filename, use an hyphen (`-`) or 


s/an hyphen/a hyphen/

Trott · 2018-01-05T00:17:45Z

Wow! You managed to get rid of all the personal pronouns. I'm kind of amazed. :-D

Trott · 2018-01-05T00:48:55Z

doc/api/synopsis.md

+
+Commands displayed in this document are shown starting with `$` or `>` 
+to replicate how they would appear in a user's terminal. 
+Do not include the `$` and `>` character they are there to 


Period after character.

Trott · 2018-01-05T00:49:24Z

Thanks for doing this!

jasnell · 2018-01-17T17:38:09Z

doc/api/synopsis.md

+Lines that don’t start with `$` or `>` character are typically showing 
+the output of the previous command.
+
+Firstly, make sure to have downloaded Node.js from [Node.js Official website](http://nodejs.org/#download).


Please move the link itself down to the end of the document

jasnell · 2018-01-17T17:38:49Z

doc/api/synopsis.md

 ```
+an output like this should appear in the terminal to indicate Node.js 


BridgeAR

A few comments. Besides that LG.

BridgeAR · 2018-01-19T12:32:25Z

doc/api/synopsis.md

+
+To install Node using a package manager, see [this guide][].
+
+


Nit: multiple lines are actually going to be shown as a single line in the output. The same applies to line 67.

BridgeAR · 2018-01-19T12:34:30Z

doc/api/synopsis.md

+Lines that don’t start with `$` or `>` character are typically showing 
+the output of the previous command.
+
+Firstly, make sure to have downloaded Node.js from [Node.js Official website][].


I personally do not like to recommend the regular download as it makes it more difficult for the user to switch to a new version. Therefore I would prefer to directly reference the guide.
It could be written as e.g.:
Firstly, make sure to have downloaded and installed Node.js. See [this guide][] for further install information.

BridgeAR · 2018-01-19T12:35:52Z

doc/api/synopsis.md


 Many of the examples in the documentation can be run similarly.

 [Command Line Options]: cli.html#cli_command_line_options
 [web server]: http.html
+[this guide]:https://nodejs.org/en/download/package-manager/
+[Node.js Official website]:http://nodejs.org/#download


Missing a empty space after the colon.

BridgeAR · 2018-01-19T12:38:10Z

doc/api/synopsis.md

+$ mkdir ~/projects
+$ cd ~/projects
+```
+Windows CMD:


It is always good to have a blank line before and after code / markdown blocks etc.

BridgeAR · 2018-01-19T12:42:15Z

doc/api/synopsis.md

+the space character in file names. 
+
+For example, use `hello-world.js` rather than `hello world.js`.
+Node.js files always end with the `.js` extension. 


I personally do not feel like this limitation should be enforced, no matter that it is good style. The point for me would be to educate the user by telling why and that is missing here.
So instead of these two paragraphs I would write e.g.:

In Node.js it is considered good style to use hypens (`-`) or underscores (`_`) to separate multiple words in filenames.

Besides that not only Node.js files end with .js but any JavaScript file. Is that part really necessary to be documented?

BridgeAR · 2018-01-19T12:42:40Z

doc/api/synopsis.md

 });

 server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
 });
 ```
+Save the file, go back to the terminal window enter the following command:


Nit: As above: a blank line before and after code blocks is always good. There are more of these cases below.

BridgeAR

LGTM with the last two open comments fixed.

BridgeAR · 2018-02-01T19:58:46Z

doc/api/synopsis.md

+Next, create a new source file in the `projects` folder
+and call it `hello-world.js`.
+
+In Node.js it is considered good style to use hyphens (`-`) or underscores (`_`) to separate


Nit: this exceeds 80 characters.

BridgeAR · 2018-02-06T22:23:27Z

It would be nice to address @Trott s comment while landing.

BridgeAR · 2018-02-06T22:24:06Z

Mini-CI https://ci.nodejs.org/job/node-test-commit-light/229/

Assuming less knowledge on the part of the reader, making it easier to get start using Node.js. PR-URL: nodejs#17977 Fixes: nodejs#17970, Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

BridgeAR · 2018-02-07T14:06:33Z

Landed in 4ac7be9 🎉

Assuming less knowledge on the part of the reader, making it easier to get start using Node.js. PR-URL: #17977 Fixes: #17970, Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

Assuming less knowledge on the part of the reader, making it easier to get start using Node.js. PR-URL: nodejs#17977 Fixes: nodejs#17970, Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

doc : being more explicit in the sypnosis

ab55bf3

Assuming less knowledge on the part of the reader, making it easier to get start using Node.js.

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jan 4, 2018

vsemozhetbyt reviewed Jan 4, 2018

View reviewed changes

vsemozhetbyt approved these changes Jan 4, 2018

View reviewed changes

Typos and corrections

2d75d3d

gibfahn reviewed Jan 4, 2018

View reviewed changes

gireeshpunathil approved these changes Jan 4, 2018

View reviewed changes

gireeshpunathil reviewed Jan 4, 2018

View reviewed changes

corrections and wrapping lines at 80 chars.

9e91b41

Trott reviewed Jan 4, 2018

View reviewed changes

timotew added 2 commits January 4, 2018 21:41

eliminating personal pronouns

5427e5a

update language aware fences

f42d3c2

Trott reviewed Jan 5, 2018

View reviewed changes

correcting punctuation and OS trademarks

bf4e20f

jasnell reviewed Jan 17, 2018

View reviewed changes

doc/api/synopsis.md Outdated

```

an output like this should appear in the terminal to indicate Node.js

Copy link

Member

jasnell Jan 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/an/An

BridgeAR reviewed Jan 19, 2018

View reviewed changes

BridgeAR removed the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Jan 19, 2018

corrections

47cf571

timotew force-pushed the patch-1 branch from a1f492f to 47cf571 Compare January 21, 2018 08:27

corrections

54b63eb

maclover7 force-pushed the master branch from bb5575a to 993b716 Compare January 26, 2018 22:02

cjihrig force-pushed the master branch from 993b716 to 082f952 Compare January 26, 2018 22:36

BridgeAR approved these changes Feb 1, 2018

View reviewed changes

break long par to new line

3afa466

Fishrock123 approved these changes Feb 2, 2018

View reviewed changes

BridgeAR added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Feb 6, 2018

BridgeAR closed this Feb 7, 2018

MylesBorins mentioned this pull request Feb 21, 2018

v9.6.0 proposal #18902

Merged

gibfahn mentioned this pull request Mar 7, 2018

doc: remove personal pronoun guidance from style guide #19186

Closed

2 tasks

gibfahn added land-on-v6.x labels Apr 13, 2018

MylesBorins mentioned this pull request Apr 13, 2018

v6.14.2 proposal #19996

Merged

MylesBorins mentioned this pull request May 2, 2018

v8.11.2 proposal #20478

Merged


		Next, create a new source file in the `projects` folder and call it `hello_world.js`.

		If you’re using more than one word in your filename, use an underscore(`_`) to separate them for simplicity and avoid using the space character in file names.

		Then, Follow this [installation guide](https://nodejs.org/en/download/package-manager/).


		Now, Create an empty project folder called `projects`, navigate into it:


		If you’re using more than one word in your filename, use an underscore(`_`) to separate them for simplicity and avoid using the space character in file names.

		For example, you’d use `hello_world.js` rather than `hello world.js`.

		```
		Your should see an output like this in your terminal to indicate Node.js server is running:

		Now, Create an empty project folder called `projects`, navigate into it:

		Linux and Mac:


		they are there to indicate the start of each command.

		You’ll see many tutorials and examples around the web that follow this

		`'Hello World!'`:

		We’ll be displaying a number of commands using a terminal, and those lines


		and call it `hello-world.js`.

		If you’re using more than one word in your filename, use an hyphen (`-`) or

		```
		an output like this should appear in the terminal to indicate Node.js


		To install Node using a package manager, see [this guide][].

doc : being more explicit in the synopsis #17977

doc : being more explicit in the synopsis #17977

Conversation

timotew commented Jan 4, 2018 • edited Loading

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

vsemozhetbyt Jan 4, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Jan 4, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt left a comment • edited Loading

Choose a reason for hiding this comment

gibfahn commented Jan 4, 2018

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

gibfahn commented Jan 4, 2018

Choose a reason for hiding this comment

Trott Jan 5, 2018 • edited Loading

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

Trott commented Jan 4, 2018 • edited Loading

Trott commented Jan 4, 2018

Choose a reason for hiding this comment

Trott commented Jan 5, 2018

Choose a reason for hiding this comment

Trott commented Jan 5, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BridgeAR 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

BridgeAR left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BridgeAR commented Feb 6, 2018

BridgeAR commented Feb 6, 2018

BridgeAR commented Feb 7, 2018

timotew commented Jan 4, 2018 •

edited

Loading

vsemozhetbyt Jan 4, 2018 •

edited

Loading

vsemozhetbyt Jan 4, 2018 •

edited

Loading

vsemozhetbyt left a comment •

edited

Loading

Trott Jan 5, 2018 •

edited

Loading

Trott commented Jan 4, 2018 •

edited

Loading