Skip to content

Commit fd40f08

Browse files
Aviv Kellertargos
Aviv Keller
authored and
targos
committed
doc: update style guide
PR-URL: #53223 Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent a96d5d1 commit fd40f08

File tree

1 file changed

+220
-103
lines changed

1 file changed

+220
-103
lines changed

‎doc/README.md

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

92-
<!-- lint disable prohibited-strings remark-lint-->
213+
### Node.js references
214+
215+
* Use _Node.js_ instead of _Node_, _NodeJS_, or similar variants.
216+
* For the executable, _`node`_ is acceptable.
93217

94-
* When referring to a version of Node.js in prose, use _Node.js_ and the version
95-
number. Do not prefix the version number with _v_ in prose. This is to avoid
96-
confusion about whether _v8_ refers to Node.js 8.x or the V8 JavaScript
97-
engine.
98-
<!-- lint enable prohibited-strings remark-lint-->
218+
### Version references
219+
220+
* Use _Node.js_ and the version number in prose. Do not prefix the version number with _v_.
99221
* OK: _Node.js 14.x_, _Node.js 14.3.1_
100222
* NOT OK: _Node.js v14_
101-
* [Use sentence-style capitalization for headings][].
102223

103-
See also API documentation structure overview in [doctools README][].
224+
<!-- lint enable prohibited-strings remark-lint-->
225+
226+
For topics not addressed here, please consult the [Microsoft Writing Style Guide][].
104227

105-
For topics not covered here, refer to the [Microsoft Writing Style Guide][].
228+
***
106229

107-
[Be direct]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences
108-
[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
109-
[Microsoft Writing Style Guide]: https://docs.microsoft.com/en-us/style-guide/welcome/
110-
[Use US spelling]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
111-
[Use sentence-style capitalization for headings]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings
112-
[Use serial commas]: https://docs.microsoft.com/en-us/style-guide/punctuation/commas
230+
[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/
231+
[US spelling]: https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
113232
[`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node
114-
[doctools README]: ../tools/doc/README.md
115-
[info string]: https://github.github.com/gfm/#info-string
116-
[language]: https://github.com/highlightjs/highlight.js/blob/HEAD/SUPPORTED_LANGUAGES.md
117233
[plugin]: https://editorconfig.org/#download
234+
[serial commas]: https://learn.microsoft.com/en-us/style-guide/punctuation/commas

0 commit comments

Comments
 (0)