Repository navigation
The Future of nodejs/examples? #883
Description
Activity
I think it should be archived. @nodejs/tsc
Reacted by Aviv Keller, Marco Ippolito, James M Snell, Michaël Zasso, Augustin Mauroy and Benjamin Gruenbaum+1 for archive
+1 for me as well.
I’ve opened a PR against the website to remove its link to the repository, as it’s the only link (that’s not in an archived repository or changelog) to the repository.
With that link removed, the repository will become an orphan, so even more of a reason to archive it.
Shouldn't we be looking to relaunch an initiative on the repo instead of archiving it?
Because the idea of putting the code there and having the explanations on the learn section of node is really not stupid. It avoids having long codeboxes.Some lasted news about this repo nodejs/next-10#154
cc @shepluI did not have time to publish and work as much as I wanted but I booked some time in the next two weeks to finalize the plan and start bringing that up to date - and link that to the documentation / new website
Jean, I'd be happy to give you a hand, but I don't have access to this repo.
IMO the problem with updating it is that it'll need to contain modern examples, so it'll have to change every update.
Rather than updating the repository, users can visit various GitHub sources, including Node.js itself, to see all sorts of real-world examples.
Shouldn't we be looking to relaunch an initiative on the repo instead of archiving it?
Because the idea of putting the code there and having the explanations on the learn section of node is really not stupid. It avoids having long codeboxes.I get what you're saying. From my perspective, the problems are:
- The information is siloed in a place where it won't get updated. We have waaaay too many siloed repositories in Node.js. IMO, the org could probably archive half of the currently not-yet-archived repositories and we'd still probably have too many. All these repositories don't result in lots of active, loosely-coupled work. They instead mostly contribute to a sense of being overwhelmed.
- I'm not convinced we should be doing this at all. Examples can be in our docs. Examples that don't fit in our docs....maybe shouldn't be hosted by us? We don't have to provide a comprehensive how-to on Node.js. When there is inevitably a problem with the examples, it makes the Node.js website look bad. We want the website to be as credible and authoritative as possible. That means not trying to be comprehensive. It means providing a reasonably restricted amount of accurate and helpful information.
We do not need to provide complete code for a "fake name generator". Interested parties can look at the many examples on GitHub by sindresorhus and others.
We do not need to provide a complete code example of how to count entries in a directory just so that we can show people how to use
yargs. People can look at theyargsdocumentation.We do not need to provide a complete code example for an
expressapp. That's what theexpressdocs are for. (And, if this repository were more active and popular, we'd be hosting examples for a dozen other third-party modules. No, please, just no.)Reacted by Aviv KellerI agree on point 1.
"maybe shouldn't be hosted by us" I don't agree with that 100%, I think we should have some sort of "official" examples. But yes the question arises "is a repo all by itself a good idea". I think yes on one condition, if we create a team "examples/content" that has the codeowner on the learn section and the example repo.
Also, there's one point on which I agree with you 200%, and that's that under no circumstances should we promote a package or make a tutorial on this page. We must restrict ourselves to node alone as a telel
If we don't archive it (which, honestly, I still think we should), we could perhaps give the website team and/or the next-10 team access instead of individuals. (I think giving individuals access to repos is an anti-pattern and wish we would not do that. We're bad about maintaining/pruning team memberships, but we are unbelievably terrible at maintaining individual permissions on repos.)
Reacted by Augustin Mauroy@ovflowd and @bmuenzenmeyer I'd like your opinion, as you're a maintainer.
Personally, I also think that personal access should not be given to a repo. But on the other hand I don't think it's a good idea to give access to the team website because that's not its purpose. But if I'm sure that the work will be done because this team has a good synergy and at the moment it's still the team that does the review for the learn section even though it's outside its remit.
PS: code vs contentI think the repository should be archived. With the redesign of the Website, I honestly believe the Learn material is enough.
Maintaining up-to-date examples is tough, and I genuinely believe our API docs + Learn material should be enough. Not to mention there's hundreds of examples and content from content creators out there that dive deep on the features of Node.js, now more than ever.
The repo should be archived IMO.
Reacted by Augustin MauroyI appreciate people wanting to help the community by providing official examples, but there are two things that are important to acknowledge:
- This is going to be a lot of work, and the work will be ongoing. Imagine the most work you think this can be. It's going to be more than that.
- Except for very simple apps (which don't need a separate repo), people are not going to agree on what should be the "official" example way to do things. I even think people aren't going to agree on the meta issue of who should be able to make that decision. Should servers use CJS or ESM? (It's a rhetorical question. Please don't have the discussion/debate here. My point is that whichever one you pick, people are going to be mad. And sure, you can do both, but there are a million things like that. That's just a prominent/obvious example. Another would be anything that involves npm/yarn/pnpm/corepack. Promise-based APIs or callbacks? Which types of examples should prioritize performance over maintainability? And on and on and on. Again, these are rhetorical questions. Please don't try to answer them here.)
If we're not archiving the repo, given the above challenges and the track record of this repo so far, I'd hope for a more robust plan then hoping that one or maybe two people volunteering get it done and do a spectacular job. Here's my possibly-unpopular suggestion: There's nothing stopping people excited about doing this from forking the repo (or starting fresh) and creating their own encyclopedic Node.js examples website or whatever. If such a thing existed and was maintained consistently, especially with the involvement of Node.js collaborators, one could propose transferring it to the nodejs org and making it official (if that's what they wanted--they could also just keep it as their own thing, which is great too).
Reacted by Augustin Mauroy, Marco Ippolito and Benjamin GruenbaumI therefore think that archiving the repo (mentioning that it is no longer maintained and that you should go to the learn section) is a good thing. And you can always mention an example external to the org on a page of the website (just mention that it's not "official"). As is already done here https://nodejs.org/en/learn/diagnostics/flame-graphs#examples
https://nodejs.org/en/learn/diagnostics/flame-graphs#examples
That page also provides a pretty good example of why we should be very cautious and deliberate about creating more content to add to our existing documentation maintenance debt. It references Solaris VMs, "new" optimizations in Node.js 8.x, Node.js 10.x, etc. None of our current content should mention any of these things except perhaps in passing. (Admittedly, the Solaris VMs are mentioned in passing, but the entire paragraph it's in should be removed IMO.)
Reacted by Benjamin GruenbaumAs this has multiple TSC LGTMs I've gone ahead and archived nodejs/examples , note this step is reversible if we ever want to use that repository again.
Thanks everyone.
Reacted by Brian Muenzenmeyer and Aviv KellerThat page also provides a pretty good example of why we should be very cautious and deliberate about creating more content to add to our existing documentation maintenance deb
We need a concerted push to have experts update the content. Maybe we open an issue for each one, to slowly comb through them. Most were a direct port of nodejs.dev
Reacted by Augustin Mauroy
The repository hasn't been updated for a few years and is missing modern examples of Node.js code. If it's not actively maintained, is it still necessary?
It serves as a reference for a few links, but in my opinion, its outdated state limits its usefulness. Maybe it should be either archived or updated?