nodejs.dev
nodejs.dev copied to clipboard
nodejs
Removing/replacing the "learn" section tutorial
In the Website Redesign meeting today, it was agreed that:
- The expansive Learn section is not appropriate for the site.
- The site should have a minimal getting-started page or two which might end with links to the OpenJS Foundation free Node.js training materials and/or a small number of other official/canonical/unimpeachably-reputable links.
We can leave the Learn material in place for people who have bookmarked it, but we shouldn't link to it. (Or is this site considered beta right now so it's OK to remove things and have them return 404?)
I don't believe the traffic we have is big enough that it would hurt by removing the learn content altogether. As if we just hide it, we're still building all these files.
They will still be available through git history. So my suggestion is:
- decide which pages should be considered getting started
- remove everything else
- consider moving these getting started pages directly to our "API Docs" section
- Remove the learn template, learn styles and anything which was just learn-specific
Regarding i18n, what should we do then? Should these pages be translatable?
And if it's hosted elsewhere (perhaps wherever the original author had it hosted?), we can probably easily include a redirect in nginx rules.
Regarding i18n, what should we do then? Should these pages be translatable?
I would imagine that we would, yes. I also imagine the process for translation probably depends on what repo they end up in. If they are in the repo alongside the API docs, it will probably be Crowdin.
In A brief history of node I'd keep the few paragraphs at the top but remove the timeline.
I'd keep the how much javascript do you need to know and point all those links to MDN examples for
- async programming
- timers
- promises
- async/await
- closures
- the event loop.
I would keep https://nodejs.dev/en/learn/nodejs-the-difference-between-development-and-production/
I don't think we need https://nodejs.dev/en/learn/ecmascript-2015-es6-and-beyond/
I don't think we need any of the Node.js Package Manager stuff. The same info can be found in the npm docs or yarn docs
And if it's hosted elsewhere (perhaps wherever the original author had it hosted?), we can probably easily include a redirect in nginx rules.
I think this was the original author https://thevalleyofcode.com/node/
I understand the rationale behind linking to MDN (or similar) in place of the current expansive Learn section. However, FWIW, I would like to advocate for the importance of having an easy to find: How do I start working with Node.js after I have installed it? guide.
For context, I help teach node.js at a university with a cohort of ~500 each semester. We ask the students to go to the nodejs.org homepage and download the LTS. Once they have finished installing it, they are completely lost. Some try to open the executable in their start menu (which of course opens the REPL), while others are fumbling around looking for a "Hello World" style example. On nodejs.org, this information is buried under Docs --> Guides --> Getting Started guide. Even if they do find it (few do), the small example using the HTTP module is hard for new folks to understand.
In short, I think it's important that we don't go from perhaps too much content currently on nodejs.dev to a situation where there is too little information for folks to get started using Node. I also think this could be a great opportunity to make the Getting Started guide be very prominent on the website and easy to follow (e.g. newcomers usually aren't particularly interested in the history of the project). For inspiration I look at, for example, the Rust and Go websites which imo have done a good job of this.
However, FWIW, I would like to advocate for the importance of having an easy to find: How do I start working with Node.js after I have installed it? guide.
We're not questioning the value of a Learn section. But the maintainability. It needs to be constantly updated, and up-to-date with current Node.js standards. Not to mention always translated to all our supported languages. It is not feasible for a small team to maintain this.
There's a ton of quality content out there to learn Node.js. OpenJS Foundation, for example.
the Rust and Go websites which imo have done a good job of this.
The Rust community has a very well established website team. And Go has full support of Google. I wish we had the resources they have for the website and translation stuff. But our reality right now isn't quite there. It doesn't mean in the future we cannot focus on expanding the learn section, but it is something that requires proper planning, guidelines and standards.
Whose the current Learn section has not.
Are you familiar with node school. Trott mentioned it briefly today. It might help with your teaching. https://nodeschool.io/#workshopper-list they are CLI programs with prompts to do different programming tasks.
I do agree we should keep some of the content. I have also used it for mentoring.
I would like to tag https://github.com/nodejs/nodejs.dev/issues/2787#issuecomment-1255160121 in this discussion as well.
The SEO rankings of /learn section has already become too high when searching to learn Node. We need to consider that many self-taught beginners might rely on the /learn section for time-to-time referencing.
The SEO rankings of /learn section has already become too high when searching to learn Node. We need to consider that many self-taught beginners might rely on the /learn section for time-to-time referencing.
Doesn't mean we cannot redirect those links to respective learning material elsewhere.
Doesn't mean we cannot redirect those links to respective learning material elsewhere.
Agreed, that was my opinion as well. However, to do that, we have to make sure that the sources we're redirecting to offer similar, if not the same, content as the current page. That will require efforts on its own, and we also need to decide on the consensus mechanism for adding these redirects.
For context, I help teach node.js at a university with a cohort of ~500 each semester. We ask the students to go to the nodejs.org homepage and download the LTS. Once they have finished installing it, they are completely lost. Some try to open the executable in their start menu (which of course opens the REPL), while others are fumbling around looking for a "Hello World" style example. On nodejs.org, this information is buried under Docs --> Guides --> Getting Started guide. Even if they do find it (few do), the small example using the HTTP module is hard for new folks to understand.
I wouldn't mind having a "Hello World" example right on the front page under the installation/download content. That's not the only option, but just saying, it's one option.
In my opinion the learn section should not be deleted.
Because if you look at many programming languages or other there is always a getting started.
Nodejs should not remove learn.
We can surely pass on a series of small tutorials. Like "Create a static website"...
And for the tutorials if we refer to a javascript feature we could redirect to MDN docs. But for features like fs we stay on our docs.
I agree with @AugustinMauroy ,
We should keep the learn section, removing where possible the use of third party libraries.
Many programming languages have the tutorial section i their official website.
or we can change the name with tutotial
We're not completely removing the section. We're removing all the content that is hard to maintain and that is out of the scope of the website, knowing there are hundreds of better materials out there.
We're going to keep a minimal getting started section for now and redirect existing links to existing material elsewhere.
But for features like fs we stay on our docs.
Who is going to maintain these docs actively? We already have API docs. We can't cover examples and create docs for every module Node.js offers, this is unfeasible.
We might reiterate this in the future, and come up with a decision to see how we can sustainably maintain tutorials if it makes sense. But for now, we decided not to.
Many programming languages have the tutorial section i their official website.
Most of the languages I'm aware of have simple getting started documentation and community-maintained tutorials, + official API docs. Of course, there are programming languages that have extensive tutorials, such as Go, Rust, et cetera. But they took time to reach to this level and a lot of planning. It was not a one-time let's do this. (I suppose)
We're not saying "NO" for tutorials, but we're aware that with our current resources and how things are structured, we cannot support a full-fledged "learn/tutorial/guides" section.
This, of course, can be revised but requires dedicated planning to come up with strategies that, again, are feasible, sustainable and maintainable.
Just saying "no" to the removal of our learn section without actually providing solutions to the problems we listed doesn't help (at all).
My two cents, I agree with removing most tutorials and adding links to external resources. However, I would caution against removing the introductions on how Node.js works, such as: its implementation of the event loop; in what order messages/events are processed and put on the call stack; and other important Node.js concepts and implementations. These are important for understanding why a Node.js application behaves the way it does and I don't believe it's covered by the API docs.
It seems backwards to rely on external resources to explain the core functionality and potential implementation specific details of the project, i.e. the project should be the authoritative resource for this.
I'm writing this with the assumption that nodejs.dev is intended to replace nodejs.org. In which case, at minimum, the "Node.js core concepts" section should be kept and probably parts of the "General" section. Though they might need some filtering.
As for providing solutions, I suppose my solution is to: keep what that which is specific to how Node.js works (it's not just a "event loop" it's "Node.js's Event Loop", etc.); and how it's different to working with JavaScript in the browser (and other engines) such using the CLI; and remove those things that are "just" a simplification of the API docs (and point to external tutorials instead).
Is there a place where one can help by suggesting how to filter the learn section in such a way? (here?) And if one wish to actively contribute to filtering through PR/Review is this the ticket to keep track of?
Loved your comment, @christian-eriksson!
Is there a place where one can help by suggesting how to filter the learn section in such a way? (here?) And if one wish to actively contribute to filtering through PR/Review is this the ticket to keep track of?
You can definitely do all the work in this Ticket, and make PRs as you wish. For example, filtering the content, and stuff.
Huge -1 to this and extremely sad it landed. This content was painstakingly written and donated to us at our request - it was extremely high quality and genuinely better than anything else we've ever had.
People have consistently linked this for several years. It's relatively beloved and the first time I've ever seen an official property consistently referred to for education.
Please revert this.
Some additional context: I just found out about this from someone asking me why all the content got deleted, as they both built a course that actively referenced it and also had a workshop in less than 24 hours that they had to remove all the links to + change their content for.
Reading through the issue comments I'm even more surprised: it's filled with people asking us not to remove content.
I... don't understand why this landed.
Some additional context: I just found out about this from someone asking me why all the content got deleted, as they both built a course that actively referenced it and also had a workshop in less than 24 hours that they had to remove all the links to + change their content for.
This seems super painstaking. I can only imagine how frustrating it is. I apologise for the disruption caused.
--
My overall opinion here: We had content on the Learn pages that were honestly super outdated and with broken links and structural issues. If we can pinpoint which content we want to add back, I'm definitely up and (strong +1) to add all the relevant content that people still want to see there.
Maintaining the content is hard, and several issues were discussed regarding maintaining it related to sustainability.
Reading through the issue comments I'm even more surprised: it's filled with people asking us not to remove content.
Most people commenting here agreed with the removal but keeping the essentials + the excellent stuff. I think we failed miserably on that premise. And we should assess what we should bring back.
@bnb wrote:
Reading through the issue comments I'm even more surprised: it's filled with people asking us not to remove content.
I... don't understand why this landed.
As a maintainer at The Odin Project, we now have several lessons where we need to find new reference material. Obviously that comes as part of the territory when collating online references into a "course". However, it wouldn't be as frustrating if the pages were just removed from the site, but having the content completely removed from the repository makes it tricky for us to even link to the md files on GitHub while we look for replacement content.
@xandora, the content is still available in the git history.
And we’re already evaluating which content to add back. I would honestly not recommend to link course materials to nodejs.dev as this website is still under development and things might change at any given time.
https://github.com/nodejs/nodejs.dev/tree/aa4239e87a5adc992fdb709c20aebb5f6da77f86 would be the git tree prior to the removal landing
Reading through the issue comments I'm even more surprised: it's filled with people asking us not to remove content.
"filled with people asking us not to remove content" does not seem accurate. Maybe I'm missing something, but I see two comments that can be characterized that way.
Regardless, the question isn't if the content is beloved or painstakingly written. The question is: Does it belong here and are we capable of maintaining it? I would prefer to see it moved somewhere else that we can redirect to.
I see that https://developer.mozilla.org/en-US/docs/Learn already has a brief Express tutorial and a Node.js-web-server-without-a-framework tutorial. I wonder if some of the nodejs.dev/learn material that goes beyond getting-started basics might be a good fit there.