Starting an Examples Initiative

[bnb]

When I started trying to learn Node.js in 0.8.x and 0.10.x, I was most frustrated by there not being any solid examples that were thorough, complete, and easy to find. The docs were way too thick and nowhere near complete enough for me to actually learn from despite folks asserting to just "read the docs" pretty consistently, leading to a pretty poor learning experience.

To this day, I hear similar complaints about our docs as an avenue to learn Node.js, and unfortunately right now I don't think that will be changing significantly within any accelerated timeframe.

As such, I think it would be valuable if we were able to provide an alternative route for learning. Specifically, learning by example is the approach I'd like to see us take. To do this, I'd suggest that we go down the avenue of starting up an Examples Initiative, focusing on building out everything from simple to complex examples for various kinds of applications that a Node.js developer would want to build.

Some examples of possible Examples:

• Web Servers
  • bare Node.js web server to serve a simple page
  • web server using Express to serve data from an API
  • web server using Fastify to serve a minimal front-end with a framework
• CLI
  • bare CLI to parse args
  • CLI using Yargs to pick a file and sit it out to the terminal
  • CLI using oclif to hit an API and prettyprint data
• Serverless
  • Using Serverless Framework to build a serverless Node.js API
  • Deploying a function to AWS Lambda (and any/every other platform folks want to contribute)
  • Deploying a function on OpenFaaS

... and more. There are a few things to note here:

• This is opinionated, just like real-world Node.js.
• This introduces frameworks, modules, and platforms, just like real-world Node.js.

My intent in proposing this initiative would be to begin to provide real-world examples for users who come looking to learn Node.js. Ideally, this would help bridge the gap between docs and real users trying to learn.

Ideally, I'd like to have us set up a few things in this process:

• Set up CI to ensure that all PRs don't break existing code
• Document why we have this initiative, what it's for, and what kind of contributions we're looking for
• Publicly share and celebrate additions to the repo from @nodejs on Twitter

Additionally, over the past ~year, we've consistently discussed having more thorough and complex examples for folks to use. Specifically, we've discussed this in the context of the Website Redesign initiative, where we'd discussed expanding the "Guides" area of the site to be open and available to all kinds of content. There may be some overlap/mutually beneficial collaboration to be done here.

[Tera99]

I would like to help with this, if I can. It sounds really useful to new users, and it would help me build my skills as well.

[keywordnew]

How might a few next steps get this initiative started? @bnb @Tera99

[Tera99]

Is there a typical process for starting an initiative that others have used? If so, I would follow that. Otherwise, some next steps I would follow in no particular order are:

• Find out who else is interested, and set up a way to begin communicating about it.
• Pick which examples we want to start with.
• Communicate with the website redesign group to make sure this is something they would go for and that we are not duplicating something they are already trying to do.

[bnb]

I would definitely agree on those steps @Tera99! Perhaps the final step there would be a good first one just to ensure we don't waste anyone's time.

I'd be more than happy to immediately contribute a few different examples – CLI, Express, Fastify (good excuse too learn), API access (GitHub API checking the Node.js org, perhaps?) are all possibilities that I could pick up relatively quickly.

So, on that last bullet: cc @amiller-gh, @nodejs/website-redesign :)

[Tera99]

I am still really a beginner, so it sounds like the best way for me to contribute would be to proof read and try out the examples. I have enough knowledge to usually be able to figure things out from the docs, but I often get stuck so I would be a good guinea pig to try the examples on.

[chasingSublimity]

Howdy all!

I'd be happy to contribute a Serverless example. I've got a fair amount of AWS experience, but am also willing to dabble with other vendors if it would be helpful.

[bnb]

@nodejs/community-committee since there wasn't quorm in the previous meeting, I'm going to ask if we can kick this off in the issue. If there aren't any objections within the next 72 hours I'll go ahead and kick off a repo + some initial work on this <3

[bnb]

also cc @nodejs/website-redesign since this may have some overlap with the work y'all have discussed in the past.

[ahmadawais]

Awesome, I'd be happy to help. Can take up writing a simple Node.js CLI example. I have a fair amount of experience writing CLIs for automation.

[Tera99]

I could contribute a simple RESTful API with Express and Google Cloud Datastore as the database. It would have 2-3 entities and support all the basic CRUD operations.

Is that along the lines of this initiative and not redundant to what anyone else is doing?

[bnb]

@Tera99 sounds good to me! For context on the redundant part, I've very actively started discussions about having something similar-ish in the Website Redesign initiative in the past. That said, I don't think the two sets of content need to be mutually exclusive.

I think we'll probably want an in-depth README explaining what each example does and the technologies used + how to get them, but otherwise it should be relatively straightforward pending objections :)

[bnb]

Next steps here are:

• Create the repo
• Ensure we can run tests across tens of projects
  • Jest's --onlyChanged should be able to help with this.
• Get a few projects in.

[chasingSublimity]

I'm still interested in helping however I can. Please don't hesitate to ping me! :)

[bnb]

This repo is now created and is able to be contributed to. @chasingSublimity, @Tera99 if you're still interested in helping out I'd be happy to catch up with y'all and see how we'd like to progress 👍

[bnb]

Link to the repo: https://github.com/nodejs/examples

[chasingSublimity]

@bnb killer! definitely still interested in helping. I'll look at the repo sometime today. Game to have a catch-up session also, w/e that looks like.

[ahmadawais]

Aha, looking forward to contributing CLI specific examples :)

[bnb]

One thing I will note: trying to get some more examples in before sharing more broadly so it’s not relatively empty

[Tera99]

Thanks for including me, sorry I can't contribute right now. I am suddenly a home school teacher. Once public school is back in, I will see if there is something I can help with. Everybody stay healthy!

[bnb]

@Tera99 no worries! You are more than welcome to join in if/when you're able. Hope things are going well and that you and your family are safe and healthy 😊

[bnb]

Going to close this issue for now since the repo is up 👍