Express: Proposal to improve Express docs/website/examples

[tinafangkunding]

Problem & Background

Hi there, we are Express.js users, and also serverless advocates. We found there are some issues about "lack of introduction to examples/cloud environment deploy issues", as the following ones:
https://github.com/expressjs/express/issues/4343
https://github.com/expressjs/express/issues/3468
https://github.com/expressjs/express/issues/4278

Therefore, in this issue, we’d like to collaborate with the express community and make a better website/content for users. First of all, we’d like to focus on adding some guidance to people who want to deploy express.js on cloud environments, especially on serverless architecture. Besides, we’d like to discuss how to help users create an express.js app quickly and easily, especially for Chinese users (express.js is very popular in China).

This proposal based on the following principles:

• Open-Source: all the content and tools used (e.g. the Serverless Framework) is open-sourced.
• Multi-Cloud Environment Support: We’ll make sure the content is neutral and the examples can be deployed to Multi-Cloud Environment.

Proposed Solution

• Multi-language Support: Translate the Readme.md, add Chinese Readme.cn.md and make it more friendly to Chinese users.

• Maintain the Chinese Express.js website. https://www.expressjs.com.cn/.
  Currently, the official website is the top result in China’s Search Engine, which means it’s an important entrance to know express.js for Chinese users.
  
  While on the official Express.js Chinese website, most of the detailed pages are still not translated to Chinese. Besides, the translated content is not easy to understand. We’d like to update and maintain this content.
  

• Update and Maintain Examples in Repo: We’d like to provide some typical examples, and these examples can be easily deployed to Multi-Cloud environments via the Serverless Framework, one of the most popular open-source development tools. Here are some examples we’d like to deliver:

  • Express.js RESTful API
  • Websocket Demo based on Express.js
  • OCR application based on Express.js
  • Translation Application based on Express.js
  • Express.js + PostgreSQL example
  • Express.js + MySQL example
  • Express.js + MongoDB example

According to a node.js survey in China 2020, Express.js is the most popular node.js framework (61.37%) in China, and many of the users deploy their express.js applications on the cloud environment, it will be great if we can support more content in the official website/repo.

Looking forward to your suggestions, and please let us know your thoughts from the community side, thanks in advance!

[dougwilson]

Multi-language Support: Translate the Readme.md, add Chinese Readme.cn.md and make it more friendly to Chinese users.

I'm not sure what value this would add, as the readme contains very little content. Adding a second when we have no full time committers who know Chinese will just result in it getting quickly out of sync. The reason we have very little content on the readme is because we focus on the website and so it really should be translated on the website content.

Maintain the Chinese Express.js website. https://www.expressjs.com.cn/.

You're welcome to do so, but as this is not a website we own, we have no say in it :)

Update and Maintain Examples in Repo: We’d like to provide some typical examples, and these examples can be easily deployed to Multi-Cloud environments via the Serverless Framework, one of the most popular open-source development tools.

Keep in mind the examples folder in this repo needs to have examples that are runnable on our CI; they are example demonstrating the Express API itself. The examples you are proposing sound like the type of examples we place on our website, not in this repo.

[tinafangkunding]

I'm not sure what value this would add, as the readme contains very little content. Adding a second when we have no full time committers who know Chinese will just result in it getting quickly out of sync. The reason we have very little content on the readme is because we focus on the website and so it really should be translated on the website content.

Agreed, then let's focus on the website content.

You're welcome to do so, but as this is not a website we own, we have no say in it :)

Gotcha, so the https://www.expressjs.com.cn/ is not the official website, do we have plans to add multi-language support for the official website? Such as https://expressjs.com/cn, I'm suggesting this because the www.expressjs.com.cn website is at the top of the SEO result, but has no clear content in it.

Keep in mind the examples folder in this repo needs to have examples that are runnable on our CI; they are example demonstrating the Express API itself. The examples you are proposing sound like the type of examples we place on our website, not in this repo.

Exactly, how about adding these templates/express related examples in the website? e.g. https://expressjs.com/templates

[dougwilson]

Gotcha, so the https://www.expressjs.com.cn/ is not the official website, do we have plans to add multi-language support for the official website? Such as https://expressjs.com/cn

We have many different languages on our website, the links to each language at at the bottom of the home page. This is the Chinese one: https://expressjs.com/zh-cn/

Exactly, how about adding these templates/express related examples in the website? e.g. https://expressjs.com/templates

Sure, but of course the best place to really have discussions around the website is in the website issue tracker https://github.com/expressjs/expressjs.com so we have the right people involved in the conversation around website changes.

[tinafangkunding]

Thanks for the guidance, it's very helpful! So should I create a new issue at https://github.com/expressjs/expressjs.com and keep tracking and updating templates there?

We have many different languages on our website, the links to each language at the bottom of the home page. This is the Chinese one: https://expressjs.com/zh-cn/

For this site, I think it's machine-translated, maybe we can update some templates on the English website first, then we can help to review the content in the Chinese website and make it more accurate.

[dougwilson]

So should I create a new issue at https://github.com/expressjs/expressjs.com and keep tracking and updating templates there?

If there is no work to be done in this repo, I would close this one out and just leave that one open. If there is work for code in this repo specifically, I would call out what it is so we can direct the discussion in this issue on what that would be. So far it has all been website changes, which are not part of this repo.

For this site, I think it's machine-translated, maybe we can update some templates on the English website first, then we can help to review the content in the Chinese website and make it more accurate.

Sure, but again, I would rather save this discussion for an issue in the website repo to ensure we have the right people involved in the conversation around website changes.

[tinafangkunding]

Sure, I think there is nothing related to this repo, I'll create a new one in the website repo, thanks!

[Gbahdeyboh]

Hi @dougwilson, could you transfer this issue to the website repo rather than him having create a new? Just so the already had conversation would still be available there.

I don't speak Chinese, neither am I from the Chinese community, but I'd like to follow up on the progress of this issue as it struck an interest in me.

[dougwilson]

Hi @Gbahdeyboh since the discussion changed what the initial proposal is, I would suggest re-creating it in the website repo such that the top post reflects the current asks after this discussion. This will make it such that the folks who are active in the website repo can find out right aware what the asks are around the website instead of needing to read back through this thread to determine what the updated asks are. That would I think be the best course of action and make it clear on the asks for the website team.

[Gbahdeyboh]

Alright! Got it.

[tinafangkunding]

Got it, I'll re-create one, thanks for your interest @Gbahdeyboh, hope we can work together on the new issue!

[Gbahdeyboh]

Definitely! @tinafangkunding, I might not be able help much with translations though. But I'll definitely be willing to help in any other way I could.

[ghost]

I am ready to contribute to that repo @tinafangkunding

[tinafangkunding]

https://github.com/expressjs/expressjs.com/issues/1176 just created a new issue in express.js website repo, feel free to add your thoughts there, thanks! cc @Gbahdeyboh @OmegaCrack

[jonchurch]

I think this issue can be closed as discussion is moving over to the website repo. Closing for now, but we can reopen if need be.