Skip to content

Commit 29b048b

Browse files
Trottrichardlau
authored andcommitted
doc: use links to MS guide in style guide
Avoid repeating too much from the Microsoft guide by providing links to it. PR-URL: #34871 Reviewed-By: Daijiro Wachi <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Franziska Hinkelmann <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
1 parent a43b7ff commit 29b048b

File tree

1 file changed

+9
-13
lines changed

1 file changed

+9
-13
lines changed

doc/guides/doc-style-guide.md

+9-13
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,8 @@ this guide.
1717
* `.editorconfig` describes the preferred formatting.
1818
* A [plugin][] is available for some editors to apply these rules.
1919
* Check changes to documentation with `make lint-md`.
20-
* Use American English spelling.
21-
* OK: _capitalize_, _color_
22-
* NOT OK: _capitalise_, _colour_
23-
* Use [serial commas][].
20+
* [Use US spelling][].
21+
* [Use serial commas][].
2422
* Avoid personal pronouns (_I_, _you_, _we_) in reference documentation.
2523
* Personal pronouns are acceptable in colloquial documentation such as guides.
2624
* Use gender-neutral pronouns and gender-neutral plural nouns.
@@ -86,31 +84,29 @@ this guide.
8684
* Use _Node.js_ and not _Node_, _NodeJS_, or similar variants.
8785
<!-- lint enable prohibited-strings remark-lint-->
8886
* When referring to the executable, _`node`_ is acceptable.
89-
* Be direct.
90-
* OK: The return value is a string.
91-
<!-- lint disable prohibited-strings remark-lint-->
92-
* NOT OK: It is important to note that, in all cases, the return value will be
93-
a string regardless.
87+
* [Be direct][].
88+
<!-- lint disable prohibited-strings remark-lint-->
9489
* When referring to a version of Node.js in prose, use _Node.js_ and the version
9590
number. Do not prefix the version number with _v_ in prose. This is to avoid
9691
confusion about whether _v8_ refers to Node.js 8.x or the V8 JavaScript
9792
engine.
9893
<!-- lint enable prohibited-strings remark-lint-->
9994
* OK: _Node.js 14.x_, _Node.js 14.3.1_
10095
* NOT OK: _Node.js v14_
101-
* For headings, use sentence case, not title case.
102-
* OK: _## Everybody to the limit_
103-
* NOT OK: _## Everybody To The Limit_
96+
* [Use sentence-style capitalization for headings][].
10497

10598
See also API documentation structure overview in [doctools README][].
10699

107100
For topics not covered here, refer to the [Microsoft Writing Style Guide][].
108101

102+
[Be direct]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences
109103
[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
110104
[Microsoft Writing Style Guide]: https://docs.microsoft.com/en-us/style-guide/welcome/
105+
[Use US spelling]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
106+
[Use sentence-style capitalization for headings]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings
107+
[Use serial commas]: https://docs.microsoft.com/en-us/style-guide/punctuation/commas
111108
[`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node
112109
[doctools README]: ../../tools/doc/README.md
113110
[info string]: https://github.github.com/gfm/#info-string
114111
[language]: https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md
115112
[plugin]: https://editorconfig.org/#download
116-
[serial commas]: https://en.wikipedia.org/wiki/Serial_comma

0 commit comments

Comments
 (0)