doc: standardize on sentence case for headers

[Trott]

Previously, our documentation headers were a mixture of title case,
sentence case, and things that were neither. For technical
documentation, the de facto standard seems to be sentence case. (See
refs below.) So let's standardize on that.

Refs: https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings
Refs: https://docs.microsoft.com/en-us/style-guide/capitalization

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[Trott]

An obvious suggestion is to make this enforced via a lint rule. While not impossible, it would be exceedingly error-prone and annoying to do so because of all the exceptions (for things like JavaScript, V8, ES modules, Wasm, WASI, Brotli, HTTP, API, Windows, POSIX, Unicode, CommonJS, Node.js, DOM, ABI, SSL, ECDH, OpenSSL, N-API, REPL, and many, many, many others). I won't stop someone else from trying, of course, but I'm not inclined to do so.

[Trott]

@nodejs/documentation

[DerekNonGeneric]

It may be worth considering that the documentation generator, which uses remark-rehype for the Markdown -> HTML conversion ends up putting the h1s (#) of these documents into the <title> tags of the generated HTML documents.

Titles are ordinarily title case. IMO, the h1 headings (and therefore document titles) should conform to some style guide (my preference is APA-style title case). To do this manually, one can use titlecaseconverter.com for the conversion, but title capitalization conformance validation can and probably should be automated by the Markdown linter.

I may have too purist of a view of this though, so really up to you.

[Trott]

Titles are ordinarily title case. IMO, the h1 headings (and therefore document titles) should conform to some style guide (my preference is APA-style title case).

I'm happy to report that the Google developer documentation style guide has a <title> tag that is in sentence case.

https://developers.google.com/style

<title>Google developer documentation style guide &nbsp;|&nbsp; Google Developers</title>

And like Google has there, the content after the | in the <title> tag will be in title case.

[DerekNonGeneric]

Is there any good reason to follow that style guide to a T? As an anecdote, I was debating w/ a Googler about conforming with their own style guide (the one mentioned) in the @amphtml repo and was told: “this isn't Google”. So, I'm under the impression that those suggestions can be taken with a grain of salt. On the other hand, if using sentence case in the title tags of technical documentation is some sort of trend and is recognized as the preferred way of doing things, then TIL and sorry for bringing it up.

[Trott]

Is there any good reason to follow that style guide to a T?

I was pointing to it as an example of something prominent and credible that uses sentence case in title tags. I did not mean to suggest that it was the final word on the topic. Microsoft's technical documentation style guide uses title casing, in contrast, for example.

[Trott]

There are other prominent/credible sites that use sentence case in title tags: MDN articles (like https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks), Wikipedia, BBC (and virtually any non-US news site like CBC and news.com.au)...

There are, of course, many counterexamples. I'm only trying to establish that sentence case in a title tag is not unusual. Title case is also very common, of course.

[Trott]

Since it's looking like I may have to wait another 3 days to get to the 7-day threshold, I want to make the case for this being a more important change than it may seem. It's an innocuous change on one level with lots of small commits. But it's also one of those things where the current inconsistency sends the subtle message that the docs are not well-reviewed and therefore not credible. From that lens, it's an important change.

[Trott]

Landed in 9918bdf...563062e