doc: typography mistake

[kovsu]

No description provided.

[nodejs-github-bot]

Review requested:

• @nodejs/modules

[Trott]

This is not a spelling mistake although it is awkward typography.

[Trott]

The backticks do not render as punctuation. They are there for formatting/typography.

It should be reworded though, because using the keyword as a verb is weird. Instead of "required" maybe we can say:

imported via `require()`

...or:

included via `require()`

...or something like that.

[kovsu]

This is not a spelling mistake although it is awkward typography.

I don't know how to express it 😀. And thanks for immediately correcting my mistake.

[JakobJingleheimer]

Do we have an official way of styling this? For example, (outside of nodejs docs) I write

require()ed
imported
import()ed

[Trott]

Do we have an official way of styling this? For example, (outside of nodejs docs) I write

require()ed
imported
import()ed

I've been looking for guidance in the Microsoft Style Guide (which we try to follow) but haven't found any. My personal opinion, though, is that we should avoid using function names as verbs.

• Both the formatted typography and the bare markdown can be confusing when we do that. That's the whole reason this PR was opened. The reader thought there was a mistake when reading the markdown.
• Not all function names use words that are verbs. Ideally we should adopt a practice that can be applied consistently, so that means not using function names as verbs because a string is not "indexOf()ed".
• It can be unclear if the function arguments are the verb's subject ("the array is map()ed") or an object ("the module is import()ed").
• Using backticks in the middle of a word in markdown usually results in jarringly out-of-proportion spacing in the resulting formatted text. You can see it in the bullet point above where it looks like "import() ed" instead of "import()ed".

For these reasons (and probably a few other reasons I haven't thought of), I think it's best to use a separate verb and let the function name be what it actually is, which is a noun. It might be good to standardize for some specific cases, though. This PR uses "included via require()" but it could have been "loaded" instead of "included" and probably a bunch of others options.

[JakobJingleheimer]

I think it would be good to establish some kind of policy, otherwise we'll end up with a bunch of these issues/PRs.

Colloquial English turns pretty much any word into a verb/past-participle by just adding "ed" to the end, so I think it's acceptable here.

RE confusion about to what it's referring, that's why I include the parentheses: require()ed. Then it's pretty clear it's a function whose name is require. It's a little less clear when it's not a function, like awaited and imported. I don't find the extra space difficult to figure out, but perhaps because I'm familiar with the convention and reading formatted markdown.

But I'm also totally fine with "included via require()" (with parens) and friends.

[nodejs-github-bot]

Landed in c4d75ea