CC @addaleax

@nodejs/documentation

These changes look good to me, but I suspect it would be better to do this by changes rather than one doc at a time. Would you be open to this approach instead?:

• Pick one of the types of changes. Maybe using pull request instead of PR or Pull Request. Or maybe capitalizing bulleted entries. But whatever it is, just one thing.
• Add it to doc/guides/doc-style-guide.md if it makes sense to do so. Put that change in one commit.
• Make the necessary change across all docs. Basically, every file linted by make lint-md. There are currently 117 of them, and you can find them all with find doc src lib benchmark test tools/doc tools/icu *.md -type f ! -path '*node_modules*' ! -path 'test/fixtures/*' -name '*.md'. Put the updates to these files in a second commit. If the changes are extensive, maybe make it one commit per file.
• Open a pull request with the two-or-more commits to make the change happen.
• Bonus points for determining if there is a way to enable a remark-lint rule for the change! But that requires a separate process. Still, noting it in the pull request is helpful.

Two advantages to this approach:

• It allows each change to be discussed separately. If people like the idea of pull request instead of PR but there is a raging debate over whether to use initial capitalization with bullet points or not, that second thing doesn't hold up the first.
• I think this approach will ease backporting.

@Trott Sounds like a good idea to me! Is it possible to have this PR merged, then I can begin work with your suggested process?

p.s. Thanks for the find command, that'll be a lifesaver.

@Trott Sounds like a good idea to me! Is it possible to have this PR merged, then I can begin work with your suggested process?

Yes, as long as you are okay with the potentially increased backporting workload for you that Rich mentioned. 👍

@Trott Sounds like a good idea to me! Is it possible to have this PR merged, then I can begin work with your suggested process?

Yes, as long as you are okay with the potentially increased backporting workload for you that Rich mentioned. 👍

I'm okay with that, I don't think I will run into any issue. Thanks for the help!

@ChrisAHolland what would also be useful is a list of the changes you will be making across the docs. For example changing to use pull request instead of PR. Documenting those things somewhere in a guide would be good to make sure we stay consistent after your pass. We might even be able to get the linter to enforce some of them.

Documenting those things somewhere in a guide

"somewhere in a guide"?

Happy to report that we already have exactly such a guide! https://github.com/nodejs/node/blob/master/doc/guides/doc-style-guide.md

@mhdawson @Trott That sounds like a good idea to me. Should I add the rule to the guide as I create pull requests for each type of edit I make?

Should I add the rule to the guide as I create pull requests for each type of edit I make?

In my opinion, yes, that would be ideal.

Should I add the rule to the guide as I create pull requests for each type of edit I make?

In my opinion, yes, that would be ideal.

Sounds good!

Landed in 441e703