Make the Intro more Beginner Friendly #8519
Description
Version
v20.10.0
Platform
Darwin MacBook-Air.local 25.1.0 Darwin Kernel Version 25.1.0: Mon Oct 20 19:34:03 PDT 2025; root:xnu-12377.41.6~2/RELEASE_ARM64_T8112 arm64
Subsystem
No response
What steps will reproduce the bug?
-
Without being familiar with Node.js, visit the Introduction to Node.js page.
-
Try to understand and use the example.
--> Note that the instruction to download Node.js is the last line of the page; if you don't already have Node installed, you can't run the example that's in the middle of the page.
--> Note that the example uses terms like “CJS”, “ESM”, and “mjs”, which aren’t explained anywhere on the page. (I submitted a pull request earlier to try to address that, but I'm a beginner and may have gotten things wrong. I should have just submitted an issue instead of trying to fix it.)
--> Note that the page has a prominent “Edit this page” link, but no obvious information about how to file an issue/bug about the content of the page.
--> Note that the page says “Node.js has a fantastic standard library, including first-class support for networking”, which appears to be a non sequitur. (It’s probably relevant, but it needs more context to look relevant to a beginner.)
--> Note that the page probably doesn’t follow a style guide. It includes grammatical awkwardnesses like “ If you use mjs version of the code”, and nonstandard use of numerals like “Those 2 objects”, and ambiguous use of “this”, and mixes “we” with “you”, and so on.
How often does it reproduce? Is there a required condition?
Happens every time you load the page without being familiar with Node.js.
What is the expected behavior? Why is that the expected behavior?
Expected: An intro tutorial that explains terms before using them, and that presents things in chronological order (such as downloading Node before using it).
What do you see instead?
See above.
Additional information
The general idea of this page is fine; it just needs a cleanup editing pass to make it clearer to newcomers. I would volunteer to do that edit, but I’m a beginner and I don’t even know enough yet to be able to use the format tool that’s required for pull requests.
The main thing that I would recommend is sitting down with someone who has written JS code before but is unfamiliar with Node, and having them go through the page and tell you where they get confused.
Activity
elysdir commentedon Jan 6, 2026
Oh, I forgot to say: Another option could be to explicitly say something like “this example is just to give you an idea of what Node.js code looks like; don’t try to run it yet.” If you take that approach, you could remove the stuff about what filenames to use and how to run it, and you could remove the ESM version, and it could just be an example briefly showing Node syntax before moving on to the next page of the tutorial.
In other words, the download instruction doesn't have to come before the example, if you don't intend readers to be able to run the example. But in that case, the page should explicitly say that it doesn't intend readers to run the example.
elysdir commentedon Jan 6, 2026
One more thing: I mentioned a style guide in passing (up above). I should have said: the main issues wrt the Node.js documentation style guide are the use of we and “Define any specialized terms or acronyms at first use.” But there are also issues that that style guide doesn’t cover; see, for example, the Numbers page in the MS writing style guide (which is the fallback for Node.js documentation style), or, similarly, the Numbers page in the Google developer documentation style guide.
MikeMcC399 commentedon Jan 6, 2026
@elysdir
In case you didn't already find it, there is a specific document Node.js Website Contributing Guide that you might find useful if you are planning additional contributions to the website.
Edit:
Perhaps one of the moderators would be able to move your valuable feedback to the website issue list https://github.com/nodejs/nodejs.org/issues, so that your issue is in the same place as your PR #8518?Done
[-]Introduction page flaws[/-][+]Make the Intro more Beginner Friendly[/+]