Modules: Refactor module documentation

[aduh95]

There are a few issues open from users complaining about the current state of the docs:

• https://github.com/nodejs/node/issues/33143
• https://github.com/nodejs/node/issues/34515
• https://github.com/nodejs/node/issues/34027
• I have probably missed other ones…

I have two open PRs (https://github.com/nodejs/node/pull/32970 and https://github.com/nodejs/node/pull/33512) on node's repo trying to find another angle, and I'd like to thank @guybedford, @GeoffreyBooth and others who reviewed them. However, both approaches have failed and a discussion have initiated about a third attempt.
I think Node.js would benefit from getting more feedback before committing to a structure for this part of the docs, and this WG felt the right place to do so.

Currently there are two pages that deal with modules:

• Modules
• ECMAScript modules

However there is no apparent logic on where a user can find documentation about features which a neither CJS nor ESM specific (package.json fields, package authoring, SourceMap support, the module core module, …).

In https://github.com/nodejs/node/pull/33512#issuecomment-666520401, it was suggested that we could use something like:

• Modules: CommonJS modules
• Modules: ECMAScript modules
• Modules: ~Package authoring~ ~configuration~ Packages
• Modules: module ~core module~ API (_including Source map v3 docs_)
• ~Modules: Source map v3 support (or could be moved to Debugger page)~

The Modules: prefix is there to make sure those entries will appear next to one another in the TOC. What are your thoughts?

_EDIT: I've included the suggestions from this thread (there are 3 comments at the time of edit)._

[DerekNonGeneric]

Thank you for creating this summary! I agree that the modules documentation needs some love, but I'm currently not in favor of merging the CJS and ESM docs. One is an experimental API, the other one is stable, and both are quite meaty. Don't get me wrong, I think some sort of restructuring needs to happen, but merging those seems like a bad idea as of right now.

When I get a chance, I will try to determine what my opinion would be on the best course of action to take.

[GeoffreyBooth]

I'm currently not in favor of merging the CJS and ESM docs

I think he's proposing four separate top-level pages, similar to what I had suggested in https://github.com/nodejs/node/pull/33512#issuecomment-666520401. The only other part was that I suggested moving the source maps section onto the Debugger page or onto its own page, since it's not really part of modules.

[guybedford]

I like the four page separation. Perhaps Package configuration over Package authoring since in theory package configuration applies to non-published packages too. The source maps documentation seems fine to go with the module core module page since the API is related to that.

[DerekNonGeneric]

I somehow missed notifications on this issue and didn't realize that there were alternatives being proposed. @aduh95 made the PR before I could dedicate any amount of time looking into what I think would be best. I still stand by https://github.com/nodejs/node/pull/34748#pullrequestreview-466862153, but also wouldn't consider it a blocker, so I've pre-approved that PR. I would wait on @guybedford and @GeoffreyBooth before landing though.

[aduh95]

Landed in core.