1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
# Node.js documentation style guide
This guide provides clear and concise instructions to help you create well-organized and readable documentation for
the Node.js community. It covers organization, spelling, formatting, and more to ensure consistency and
professionalism across all documents.
## Table of contents
1. [General Guidelines](#general-guidelines)
2. [Writing Style](#writing-style)
3. [Punctuation](#punctuation)
4. [Document Structure](#document-structure)
5. [API Documentation](#api-documentation)
6. [Code Blocks](#code-blocks)
7. [Formatting](#formatting)
8. [Product and Project Naming](#product-and-project-naming)
***
## General guidelines
### File naming
* **Markdown Files:** Use `lowercase-with-dashes.md`.
* Use underscores only if they are part of the topic name (e.g., `child_process`).
* Some files, like top-level Markdown files, may be exceptions.
### Text wrapping
* Wrap documents at 120 characters per line to enhance readability and version control.
### Editor configuration
* Follow the formatting rules specified in `.editorconfig`.
* A [plugin][] is available for some editors to enforce these rules.
### Testing documentation
* Validate documentation changes using `make test-doc -j` or `vcbuild test-doc`.
***
## Writing style
### Spelling and grammar
* **Spelling:** Use [US spelling][].
* **Grammar:** Use clear, concise language. Avoid unnecessary jargon.
### Commas
* **Serial Commas:** Use [serial commas][] for clarity.
* Example: _apples, oranges<b>,</b> and bananas_
### Pronouns
* Avoid first-person pronouns (_I_, _we_).
* Exception: Use _we recommend foo_ instead of _foo is recommended_.
### Gender-neutral language
* Use gender-neutral pronouns and plural nouns.
* OK: _they_, _their_, _them_, _folks_, _people_, _developers_
* NOT OK: _his_, _hers_, _him_, _her_, _guys_, _dudes_
### Terminology
* Use precise technical terms and avoid colloquialisms.
* Define any specialized terms or acronyms at first use.
***
## Punctuation
### Terminal punctuation
* Place inside parentheses or quotes if the content is a complete clause.
* Place outside if the content is a fragment of a clause.
### Quotation marks
* Use double quotation marks for direct quotes.
* Use single quotation marks for quotes within quotes.
### Colons and semicolons
* Use colons to introduce lists or explanations.
* Use semicolons to link closely related independent clauses.
***
## Document structure
### Headings
* Start documents with a level-one heading (`#`).
* Use subsequent headings (`##`, `###`, etc.) to organize content hierarchically.
### Links
* Prefer reference-style links (`[a link][]`) over inline links (`[a link](http://example.com)`).
### Lists
* Use bullet points for unordered lists and numbers for ordered lists.
* Keep list items parallel in structure.
### Tables
* Use tables to present structured information clearly. Ensure they are readable in plain text.
***
## API documentation
### YAML comments
* Update the YAML comments associated with the API, especially when introducing or deprecating an API.
### Usage examples
* Provide a usage example or a link to an example for every function.
### Parameter descriptions
* Clearly describe parameters and return values, including types and defaults.
* Example:
```markdown
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
```
***
## Code blocks
### Language-aware fences
* Use language-aware fences (e.g., ` ```js `) for code blocks.
* **Info String:** Use the appropriate info string from the following list:
| Language | Info String |
| ---------------- | ------------ |
| Bash | `bash` |
| C | `c` |
| CommonJS | `cjs` |
| CoffeeScript | `coffee` |
| Terminal Session | `console` |
| C++ | `cpp` |
| Diff | `diff` |
| HTTP | `http` |
| JavaScript | `js` |
| JSON | `json` |
| Markdown | `markdown` |
| EcmaScript | `mjs` |
| Powershell | `powershell` |
| R | `r` |
| Plaintext | `text` |
| TypeScript | `typescript` |
* Use `text` for languages not listed until their grammar is added to [`remark-preset-lint-node`][].
### Code comments
* Use comments to explain complex logic within code examples.
* Follow the standard commenting style of the respective language.
***
## Formatting
### Escaping characters
* Use backslash-escaping for underscores, asterisks, and backticks: `\_`, `\*`, `` \` ``.
### Naming conventions
* **Constructors:** Use PascalCase.
* **Instances:** Use camelCase.
* **Methods:** Indicate methods with parentheses: `socket.end()` instead of `socket.end`.
### Function arguments and returns
* **Arguments:**
```markdown
* `name` {type|type2} Optional description. **Default:** `value`.
```
Example:
```markdown
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
```
* **Returns:**
```markdown
* Returns: {type|type2} Optional description.
```
Example:
```markdown
* Returns: {AsyncHook} A reference to `asyncHook`.
```
***
## Product and project naming
<!-- lint disable prohibited-strings remark-lint-->
### Official styling
* Use official capitalization for products and projects.
* OK: JavaScript, Google's V8
* NOT OK: Javascript, Google's v8
### Node.js references
* Use _Node.js_ instead of _Node_, _NodeJS_, or similar variants.
* For the executable, _`node`_ is acceptable.
### Version references
* Use _Node.js_ and the version number in prose. Do not prefix the version number with _v_.
* OK: _Node.js 14.x_, _Node.js 14.3.1_
* NOT OK: _Node.js v14_
<!-- lint enable prohibited-strings remark-lint-->
For topics not addressed here, please consult the [Microsoft Writing Style Guide][].
***
[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/
[US spelling]: https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
[`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node
[plugin]: https://editorconfig.org/#download
[serial commas]: https://learn.microsoft.com/en-us/style-guide/punctuation/commas
|
