Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: standardize on sentence case for headers #33889

Closed
wants to merge 0 commits into from

Conversation

Trott
Copy link
Member

@Trott Trott commented Jun 15, 2020

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

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jun 15, 2020
@Trott
Copy link
Member Author

Trott commented Jun 15, 2020

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
Copy link
Member Author

Trott commented Jun 15, 2020

@nodejs/documentation

doc/api/cli.md Outdated Show resolved Hide resolved
doc/api/esm.md Outdated Show resolved Hide resolved
@Trott Trott added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Jun 15, 2020
@DerekNonGeneric
Copy link
Contributor

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
Copy link
Member Author

Trott commented Jun 16, 2020

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
Copy link
Contributor

DerekNonGeneric commented Jun 16, 2020

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
Copy link
Member Author

Trott commented Jun 16, 2020

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
Copy link
Member Author

Trott commented Jun 16, 2020

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
Copy link
Member Author

Trott commented Jun 19, 2020

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 added a commit that referenced this pull request Jun 19, 2020
Trott added a commit that referenced this pull request Jun 19, 2020
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. This commit follows a
commit implementing this standard. This commit adds it to the style
guide.

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

PR-URL: #33889
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@Trott
Copy link
Member Author

Trott commented Jun 19, 2020

Landed in 9918bdf...563062e

@Trott Trott closed this Jun 19, 2020
@Trott Trott deleted the sentence-case branch June 19, 2020 15:14
Trott added a commit to Trott/io.js that referenced this pull request Jun 19, 2020
Trott added a commit to Trott/io.js that referenced this pull request Jun 19, 2020
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. This commit follows a
commit implementing this standard. This commit adds it to the style
guide.

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

PR-URL: nodejs#33889
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
codebytere pushed a commit that referenced this pull request Jun 27, 2020
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. This commit follows a
commit implementing this standard. This commit adds it to the style
guide.

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

PR-URL: #33889
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@codebytere codebytere mentioned this pull request Jun 28, 2020
codebytere pushed a commit that referenced this pull request Jun 30, 2020
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. This commit follows a
commit implementing this standard. This commit adds it to the style
guide.

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

PR-URL: #33889
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Trott added a commit to Trott/io.js that referenced this pull request Jul 6, 2020
codebytere pushed a commit that referenced this pull request Jul 8, 2020
PR-URL: #33889
Backport-PR-URL: #33964
Refs: https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings
Refs: https://docs.microsoft.com/en-us/style-guide/capitalization
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
codebytere pushed a commit that referenced this pull request Jul 8, 2020
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. This commit follows a
commit implementing this standard. This commit adds it to the style
guide.

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

PR-URL: #33889
Backport-PR-URL: #33964
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@codebytere codebytere mentioned this pull request Jul 13, 2020
MylesBorins pushed a commit that referenced this pull request Jul 14, 2020
Backport-PR-URL: #33961
PR-URL: #33889
Refs: https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings
Refs: https://docs.microsoft.com/en-us/style-guide/capitalization
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Jul 14, 2020
@targos targos removed the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 25, 2021
tniessen added a commit to tniessen/node that referenced this pull request Jan 18, 2022
tniessen added a commit that referenced this pull request Jan 18, 2022
Refs: #33889

PR-URL: #41577
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Mestery <mestery@protonmail.com>
thedull pushed a commit to thedull/node that referenced this pull request Jan 18, 2022
Refs: nodejs#33889

PR-URL: nodejs#41577
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Mestery <mestery@protonmail.com>
BethGriggs pushed a commit that referenced this pull request Jan 25, 2022
Refs: #33889

PR-URL: #41577
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Mestery <mestery@protonmail.com>
Linkgoron pushed a commit to Linkgoron/node that referenced this pull request Jan 31, 2022
Refs: nodejs#33889

PR-URL: nodejs#41577
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Mestery <mestery@protonmail.com>
tniessen added a commit to tniessen/node that referenced this pull request Feb 2, 2022
nodejs-github-bot pushed a commit that referenced this pull request Feb 3, 2022
Refs: #33889

PR-URL: #41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
VoltrexKeyva pushed a commit to VoltrexKeyva/node that referenced this pull request Feb 3, 2022
Refs: nodejs#33889

PR-URL: nodejs#41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
ruyadorno pushed a commit that referenced this pull request Feb 8, 2022
Refs: #33889

PR-URL: #41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
danielleadams pushed a commit that referenced this pull request Feb 26, 2022
Refs: #33889

PR-URL: #41577
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Mestery <mestery@protonmail.com>
danielleadams pushed a commit that referenced this pull request Mar 2, 2022
Refs: #33889

PR-URL: #41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
danielleadams pushed a commit that referenced this pull request Mar 3, 2022
Refs: #33889

PR-URL: #41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
danielleadams pushed a commit to danielleadams/node that referenced this pull request Mar 4, 2022
Refs: nodejs#33889

PR-URL: nodejs#41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
danielleadams pushed a commit to danielleadams/node that referenced this pull request Mar 4, 2022
Refs: nodejs#33889

PR-URL: nodejs#41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
danielleadams pushed a commit that referenced this pull request Mar 8, 2022
Refs: #33889

PR-URL: #41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
danielleadams pushed a commit that referenced this pull request Mar 14, 2022
Refs: #33889

PR-URL: #41829
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants