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 1 commit
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
54 changes: 46 additions & 8 deletions doc/api/synopsis.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,43 @@ 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!'`:

Firstly, Make sure you have downloaded Node.js from [Node.js Official website](http://nodejs.org/#download).
Copy link
Contributor

Choose a reason for hiding this comment

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

Make -> make?

Then, Follow this [installation 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.

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.

Copy link
Contributor

Choose a reason for hiding this comment

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

Follow -> follow?


Copy link
Member

Choose a reason for hiding this comment

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

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


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

Choose a reason for hiding this comment

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

Create -> create?

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


Linux and Mac:
Copy link
Member

Choose a reason for hiding this comment

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

May be UNIX rather than Linux and Mac ?

Copy link
Member

@Trott Trott Jan 5, 2018

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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


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?

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

```txt
$ 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.

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

Windows PowerShell:

```txt
> 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 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.
Copy link
Contributor

Choose a reason for hiding this comment

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

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


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

@vsemozhetbyt vsemozhetbyt Jan 4, 2018

Choose a reason for hiding this comment

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

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.

Node.js files always end with the `.js` extension.

open `hello_world.js` in your favorite text editor and paste in the following content.
Copy link
Contributor

Choose a reason for hiding this comment

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

open -> Open?



```js
const http = require('http');
Expand All @@ -22,21 +56,25 @@ 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}/`);
});
```

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

Choose a reason for hiding this comment

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

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


```txt
$ node example.js
Server running at http://127.0.0.1:3000/
$ node hello_world.js
```
Your should see an output like this in your terminal to indicate Node.js server is running:
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt Jan 4, 2018

Choose a reason for hiding this comment

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

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

```javascript
Copy link
Member

Choose a reason for hiding this comment

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

Maybe remove the javascript here.

Server running at http://127.0.0.1:3000/
````
Now, Open your favorite browser and visit `http://127.0.0.1:3000`.
Copy link
Contributor

Choose a reason for hiding this comment

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

Open ->open?


You should see the string `Hello, world!`.

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

Expand Down