nodejs
docs: making the docs interactive and newbie friendly
Affected URL(s)
No response
Description of the problem
I'm a newbie and have been trying to learn Node.js from the official docs but I continuously find myself jumping around different modules to know about a certain terms/classes that were used or mentioned in the module that I was trying to read.
When I was reading the learn section for Node.js, it also got me into some troubles. Similarly in that page, it mentioned some terms that I was not familiar with. There was no mention/explanation for the prerequisites in the previous sections that could have potentially helped to get rid of these issues.
I will try to give an example from the fs module. In <FileHandle> class docs, it mentioned <EventEmitter>, but that's from a different module which I did not start read yet. In the same section it also mentions instances of FileHandle are created by fsPromises.open(), but it did not mention what will be the arguments inside that method.
There is also some silly mistakes that I made at the beginning, for example, path.basename(path[, suffix]) I thought that suffix is supposed to be inside and array or counts as an array. But, now I know that, the square brackets represent optional arguments, learned out of curiosity.
When you mention "interative" docs, what do mean?
If the issue is only the docs(text) itself, I recommend you open a few PRs on top of it. It would be great for your learning, since you will need to understand the doc/module and gaps in that doc to propose a fix.
When you mention "interative" docs, what do mean?
yeah, now i understand why chatgpt told me not to use the word interactive as it sound very vague.
what i meant by interactive is making things easier to follow along, and adding practical examples that learners can write in their text editor and get a similar type of results. it may help us feel right at home.
there is a page which mentions the prerequisites of learning nodejs, which helped me a lot! i think something similar articles can be added, which will explain in which order the docs should be read, to learn the nodejs. i know that, not all of them are needed for everyone and in everyday task. but it may help learning the modules easily and efficiently.
If the issue is only the docs(text) itself, I recommend you open a few PRs on top of it. It would be great for your learning, since you will need to understand the doc/module and gaps in that doc to propose a fix.
i think i'm too immature on javascript ecosystem, that i may make some silly mistakes! but, i will try my best, thanks!
If you are begginer I would recommend you to start from video tutorials and use documentation as a reference and once you understand the basic things, the doc makes more sense than videos. One suggestion from my end to the core node team if we can make something similar to Symfony casts or laracasts ie official video series it would be more helpful for the beginners. Currently there are lot of scattered videos in internet and most of them are not updated with the latest version changes.
If you are begginer I would recommend you to start from video tutorials and use documentation as a reference Currently there are lot of scattered videos in internet and most of them are not updated with the latest version changes.
i used to watch videos but now i completely rely on docs and articles to learn something new. a core reason for that is, i always get to learn and use the latest and greatest technologies. which is not common in video tutorials.
seems like, it has been a long time since people were having troubles with this https://www.reddit.com/r/node/comments/9e3bxn/i_want_to_study_the_nodejs_in_documentation_but/
I think I understood the problem, it's all happening because of ascending order. I don't think the entire docs can be rewritten or reordered, that's a huge refactor! So, I'm closing the issue for now.