EFI: Express documentation (expressjs.com website)

[crandmck]

Documentation needs to be considered as a key task and "first-class citizen". I'm copying some information from #198 here and I'll close that issue in favor of this one. NOTE: I added the top-priority label to this so it will be automatically added to the TC meeting agenda, as I'd like to discuss some items with the TC.

Top-level doc work includes:

• Fixing known errors/problems in the existing (4.x) doc (see Doc PRs and issues)
• Improving the completeness and accuracy of existing (4.x & 5.x) doc (via new issues/PRs)
• Removing old/irrelevant info in the existing (4.x) doc

5.x specific work:

• Documenting new 5.x releases (API doc)
• Writing tasks and tutorials for 5.x

Other (non-content) work:

• Improving the usability of the doc site
• Improving the tooling/framework used for the doc (Jekyll currently)

Doc PRs and issues

I've been working to review and merge as many PRs as possible. I added some labels to help with organization. So far, I've labeled open PRs:

• Needs tech review for change that I'm not comfortable merging until reviewed by someone with deeper tech knowledge. This could be a TC member, or anyone else who wants to help with docs, e.g. @waleedtariq109.
• 5.x for changes that are specific to 5.x
• UI for changes to the site interface itself (not content).
• localization changes related to translations, i.e. non-English content.
• enhancement for changes/additions to "ancillary" doc pages, e.g. Template engines, Frameworks and other stuff that's not specifically technical docs for Express, related middleware, etc. These are lower priority since they are not the core mission of the docs, and IMO we could even move this info into the GH wiki to reduce the number of incoming PRs/issues.

What's the best way for me to get tech reviews for doc changes? I've just been tagging folks like @UlisesGascon but is there a better way?

Next, I'll try to review all the open issues to label and triage them.

Removing old/irrelevant info (DONE)

NOTE: This was done with https://github.com/expressjs/expressjs.com/pull/1484

I wonder if we can just remove these pages:

• https://expressjs.com/en/resources/open-source-using-express.html
• https://expressjs.com/en/resources/learning.html
• https://expressjs.com/en/advanced/pm.html

While these topics are relevant and there are historical reasons for having these pages, IMO they are beyond the scope of the Express documentation. There is so much higher priority work to do and we should focus on documenting Express itself and closely-related stuff in pillarjs and jshttp.

Related discussion: https://github.com/expressjs/discussions/issues/105

See also the "enhancement" label mentioned above.

I'd also like to discuss removing the BLM banner that TJ added via direct commit several years ago. While it's of course a worthy cause I don't think it's appropriate and it was added outside the normal PR process.

Work for 5.x

We need to think about what doc tasks re to 5.x will give us the most "bang for the buck," e.g. writing tutorials, enhancing the migration guide / summarizing diffs with 4.x, detailed API doc review, etc.

Committers

Finally, we need to review the approved committers to the repo: https://github.com/expressjs/discussions/settings.

Issue triage

We should have a general process to triage incoming issues (and PRs). For example:

• Any issue that's merely a question (e.g. "How do I do xyz in Express?") should be labeled as question and closed with stock answer that we don't provide tech support.
• I'll work to document the rules I outlined in the "Doc PRs and issues" section above and we should follow them, assuming we agree.
• Issues that are about the software (i.e. bug reports, etc.) and not the docs should be moved to the express or other relevant repo (more specifics TBD). It's common to require some investigation to determine if something is actually a issue in the software or an issue with the docs. For that reason, issues will often require technical review and discussion to get to the root issue.
• Anything else?

[bjohansebas]

We can draw inspiration from this copy of the Express documentation made with Starlight:

Repo: https://github.com/bjohansebas/expressjs.com URL: https://expressjs-docs.vercel.app

[bjohansebas]

Static site generators like VitePress, Docusaurus, or Starlight use MDX. We could gradually replace Liquid (used by Jekyll) with MDX in various PRs, which would then facilitate a migration to a more modern framework later on.