doc: Enhancing guides by fixing and making grammar more consistent

[ChrisAHolland]

This pull request is the beginning of me overviewing the entirety of the docs/guides/ folder.

I am aiming to enhance the grammar and make notations more consistent to improve readability and professionalism.

If this pull request is well received and lands, I will continue with the rest of the guides!

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[ChrisAHolland]

CC @addaleax

[Trott]

@nodejs/documentation

[Trott]

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.

[ChrisAHolland]

@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.

[addaleax]

@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. 👍

[ChrisAHolland]

@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!

[mhdawson]

@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.

[Trott]

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

[ChrisAHolland]

@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?

[Trott]

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.

[ChrisAHolland]

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!

[addaleax]

Landed in 441e703