Commit 29b048b
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 <daijiro.wachi@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>1 parent a43b7ff commit 29b048b
1 file changed
Lines changed: 9 additions & 13 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -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