Vague doc

[the-wazz]

• 8.9.3 LTS
• Win10
• Docs

Total noob here. I hit a wall on this page - https://nodejs.org/api/synopsis.html. Happens a lot, in all kinds of docs. I understand what's written, then get to: "To run the server, put the code into a file called example.js and execute it with Node.js:

$ node example.js
Server running at http://127.0.0.1:3000/

Q: i put the js file on my desktop. Is that ok?
Q: type the first line in a command prompt?
Q: is the second line a result or do I type that too?
Q: just type as-is? do i have to navigate to a specific dir?

I tried just typing the first line and nothing worked. Again, total noob here, but I kind of expect this to just work. There are clearly instructions missing. If you want people to get it, then please include everything, assume nothing. Please. Really tired of missing "obvious" instructions that are NOT obvious. Thanks.

[ORESoftware]

welcome newbie.

what actually happens when you copy and paste the code, and save it to example.js and then run it with node? is there an error message? any feedback?

yes for that code sample, all you need is one file (example.js). that is because the dependencies referenced in that file are all baked into node.js - they are core libraries. you can save the file anywhere you want, including your Desktop.

If you are on windows, I recommend installing the Git Bash shell.
https://git-scm.com/downloads

to answer your question:

$ node example.js # this is the command you type into the shell, type it, then hit return/enter
Server running at http://127.0.0.1:3000/  # this is the stdout that appears in your shell after you hit return

[gibfahn]

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

So the problem is that this line isn't clear right?

I think we could definitely do with more detail here, everyone starts with no knowledge of how to use the command line and run scripts etc. Of course there's always a trade-off, too much information makes it hard to find the important parts.

I think this StackOverflow question should be clear enough:
https://stackoverflow.com/questions/6737824/how-to-run-a-hello-js-file-in-node-js-on-windows

We should probably either link to a simillar resource, or include that information in the docs.

For comparison, here's the equivalent in the Rust Book:
https://doc.rust-lang.org/book/second-edition/ch01-01-installation.html
https://doc.rust-lang.org/book/second-edition/ch01-02-hello-world.html

Those pages go into a lot more detail. It's worth noting though that Rust has a separate set of api documentation: https://doc.rust-lang.org/std/ , so it's not quite analogous.

[ORESoftware]

@the-wazz you might want to find someone IRL who can help you get familiar with the command line. At some point it helps to have someone sit next to you and get your started especially with the command line etc

[the-wazz]

@ORESoftware i ran $ node example.js and got

'$' is not recognized as an internal or external command,
operable program or batch file.

i tried it without the dollar sign, just to see, and got errors.

i changed directory (cd) to the desktop and it ran. that's all that's missing, 'change directory...'.

it's a simple thing, and yes, it's me, but i was reading documentation. i can't help but say that a pretty important instruction was missing, and it's amazing how often docs that use the command-line are missing that instruction. it's not a given; not really.

and to push it a little more (sorry), this is your usage page -- how to use node.js -- and the instruction is, "put the code into a file called example.js and execute it with Node.js." Umm..., you get it.

thanks for the feedback. sincerely.

[ORESoftware]

sometimes paper/webdocs cannot substitute for first-hand experience, and in-person instruction

[gibfahn]

@the-wazz did you try the stackoverflow link I posted? It includes all the steps, including the cd: https://stackoverflow.com/questions/6737824/how-to-run-a-hello-js-file-in-node-js-on-windows ?

As I said, we should improve the documentation here. In a section dedicated to telling you how to run the examples, there's no reason we couldn't tell you how to cd to the directory.

sometimes paper/webdocs cannot substitute for first-hand experience, and in-person instruction

I learned how to use a command line from a guide, and in this case I think docs can be more clear about the basic steps.

[gibfahn]

@the-wazz I've raised an issue to track adding more info at nodejs/node#17970. If you'd like to have a stab at raising a PR to improve the documentation that'd be great, otherwise you can just track the issue's progress.

I'm going to close this out, as I think your question has been answered (and your request for doc improvements is tracked in the nodejs/node issue). If you have further questions feel free to comment in either issue.