Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc : being more explicit in the synopsis #17977

Closed
wants to merge 9 commits into from
Closed
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 68 additions & 9 deletions doc/api/synopsis.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,62 @@ Please see the [Command Line Options][] document for information about
different options and ways to run scripts with Node.js.

## Example

An example of a [web server][] written with Node.js which responds with
`'Hello World'`:
`'Hello World!'`:

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 indicate the start of each command.

There are many tutorials and examples that follow this
convention: `$` or `>` for commands run as a regular user, and `#`
for commands that should be executed as an administrator.

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).
Copy link
Member

Choose a reason for hiding this comment

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

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


Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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

To install Node using a package manager, see [this guide](https://nodejs.org/en/download/package-manager/).


Copy link
Member

Choose a reason for hiding this comment

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

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

Now, create an empty project folder called `projects`, navigate into it:
Copy link
Member

Choose a reason for hiding this comment

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

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:

Project folder can be named base on user's current project title but
this example will use `projects` as the project folder.

UNIX :

Copy link
Member

Choose a reason for hiding this comment

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

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

```console
$ mkdir ~/projects
$ cd ~/projects
```
Windows CMD:
Copy link
Member

Choose a reason for hiding this comment

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

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

```console
> mkdir %USERPROFILE%\projects
> cd %USERPROFILE%\projects
```

Windows PowerShell:

```console
> mkdir $env:USERPROFILE\projects
> cd $env:USERPROFILE\projects
```

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

If filename has more than one word, use a hyphen(`-`) or
an underscore(`_`) to separate them for simplicity and avoid using
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.
Copy link
Member

Choose a reason for hiding this comment

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

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?


Open `hello-world.js` in any preferred text editor and paste in the following
content.


```js
const http = require('http');
Expand All @@ -22,21 +75,27 @@ const port = 3000;
const server = http.createServer((req, res) => {
res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Hello World\n');
res.end('Hello World!\n');
});

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:
Copy link
Member

Choose a reason for hiding this comment

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

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


To run the server, put the code into a file called `example.js` and execute
it with Node.js:

```txt
$ node example.js
Server running at http://127.0.0.1:3000/
```console
$ node hello-world.js
```
an output like this should appear in the terminal to indicate Node.js
Copy link
Member

Choose a reason for hiding this comment

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

s/an/An

server is running:
```console
Server running at http://127.0.0.1:3000/
````
Now, open any preferred web browser and visit `http://127.0.0.1:3000`.

If the browser displays the string `Hello, world!`, that indicates
the server is working.

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

Expand Down