@@ -17,10 +17,8 @@ this guide.
17
17
* ` .editorconfig ` describes the preferred formatting.
18
18
* A [ plugin] [ ] is available for some editors to apply these rules.
19
19
* 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] [ ] .
24
22
* Avoid personal pronouns (_ I_ , _ you_ , _ we_ ) in reference documentation.
25
23
* Personal pronouns are acceptable in colloquial documentation such as guides.
26
24
* Use gender-neutral pronouns and gender-neutral plural nouns.
@@ -86,31 +84,29 @@ this guide.
86
84
* Use _ Node.js_ and not _ Node_ , _ NodeJS_ , or similar variants.
87
85
<!-- lint enable prohibited-strings remark-lint-->
88
86
* 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-->
94
89
* When referring to a version of Node.js in prose, use _ Node.js_ and the version
95
90
number. Do not prefix the version number with _ v_ in prose. This is to avoid
96
91
confusion about whether _ v8_ refers to Node.js 8.x or the V8 JavaScript
97
92
engine.
98
93
<!-- lint enable prohibited-strings remark-lint-->
99
94
* OK: _ Node.js 14.x_ , _ Node.js 14.3.1_
100
95
* 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] [ ] .
104
97
105
98
See also API documentation structure overview in [ doctools README] [ ] .
106
99
107
100
For topics not covered here, refer to the [ Microsoft Writing Style Guide] [ ] .
108
101
102
+ [ Be direct ] : https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences
109
103
[ Javascript type ] : https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
110
104
[ 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
111
108
[ `remark-preset-lint-node` ] : https://github.com/nodejs/remark-preset-lint-node
112
109
[ doctools README ] : ../../tools/doc/README.md
113
110
[ info string ] : https://github.github.com/gfm/#info-string
114
111
[ language ] : https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md
115
112
[ plugin ] : https://editorconfig.org/#download
116
- [ serial commas ] : https://en.wikipedia.org/wiki/Serial_comma
0 commit comments