doc: update style guide

avivkeller · marco-ippolito · commit 80edcdf8991b · 2024-11-17T11:51:40.000+01:00
PR-URL: #53223 Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/README.md b/doc/README.md
@@ -1,117 +1,234 @@
-# Documentation style guide
-
-This style guide helps us create organized and easy-to-read documentation. It
-provides guidelines for organization, spelling, formatting, and more.
-
-These are guidelines rather than strict rules. Content is more important than
-formatting. You do not need to learn the entire style guide before contributing
-to documentation. Someone can always edit your material later to conform with
-this guide.
-
-* Documentation is in markdown files with names formatted as
-  `lowercase-with-dashes.md`.
-  * Use an underscore in the filename only if the underscore is part of the
-    topic name (e.g., `child_process`).
-  * Some files, such as top-level markdown files, are exceptions.
-* Documents should be word-wrapped at 80 characters.
-* `.editorconfig` describes the preferred formatting.
-  * A [plugin][] is available for some editors to apply these rules.
-* Check changes to documentation with `make test-doc -j` or `vcbuild test-doc`.
-* [Use US spelling][].
-* [Use serial commas][].
+# 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: _we recommend foo_ is preferable to _foo is recommended_.
-* Use gender-neutral pronouns and gender-neutral plural nouns.
+  * 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_
-* When combining wrapping elements (parentheses and quotes), place terminal
-  punctuation:
-  * Inside the wrapping element if the wrapping element contains a complete
-    clause.
-  * Outside of the wrapping element if the wrapping element contains only a
-    fragment of a clause.
-* Documents must start with a level-one heading.
-* Prefer affixing links (`[a link][]`) to inlining links
-  (`[a link](http://example.com)`).
-* When documenting APIs, update the YAML comment associated with the API as
-  appropriate. This is especially true when introducing or deprecating an API.
-* When documenting APIs, every function should have a usage example or
-  link to an example that uses the function.
-* For code blocks:
-  * Use [language][]-aware fences. (<code>\`\`\`js</code>)
-
-  * For the [info string][], use one of the following.
-
-    | Meaning       | Info string  |
-    | ------------- | ------------ |
-    | Bash          | `bash`       |
-    | C             | `c`          |
-    | C++           | `cpp`        |
-    | CoffeeScript  | `coffee`     |
-    | Diff          | `diff`       |
-    | HTTP          | `http`       |
-    | JavaScript    | `js`         |
-    | JSON          | `json`       |
-    | Markdown      | `markdown`   |
-    | Plaintext     | `text`       |
-    | Powershell    | `powershell` |
-    | R             | `r`          |
-    | Shell Session | `console`    |
-
-    If one of your language-aware fences needs an info string that is not
-    already on this list, you may use `text` until the grammar gets added to
-    [`remark-preset-lint-node`][].
-
-  * Code need not be complete. Treat code blocks as an illustration or aid to
-    your point, not as complete running programs. If a complete running program
-    is necessary, include it as an asset in `assets/code-examples` and link to
-    it.
-* When using underscores, asterisks, and backticks, please use
-  backslash-escaping: `\_`, `\*`, and ``\` ``.
-* Constructors should use PascalCase.
-* Instances should use camelCase.
-* Denote methods with parentheses: `socket.end()` instead of `socket.end`.
-* Function arguments or object properties should use the following format:
-  * ``* `name` {type|type2} Optional description. **Default:** `value`.``
-  <!--lint disable maximum-line-length remark-lint-->
-  * For example: <code>\* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code>
-  <!--lint enable maximum-line-length remark-lint-->
-  * The `type` should refer to a Node.js type or a [JavaScript type][].
-* Function returns should use the following format:
-  * <code>\* Returns: {type|type2} Optional description.</code>
-  * E.g. <code>\* Returns: {AsyncHook} A reference to `asyncHook`.</code>
-* Use official styling for capitalization in products and projects.
+
+### 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
-  <!--lint disable prohibited-strings remark-lint-->
   * NOT OK: Javascript, Google's v8
-* Use _Node.js_ and not _Node_, _NodeJS_, or similar variants.
-  <!-- lint enable prohibited-strings remark-lint-->
-  * When referring to the executable, _`node`_ is acceptable.
-* [Be direct][].
 
-<!-- lint disable prohibited-strings remark-lint-->
+### Node.js references
+
+* Use _Node.js_ instead of _Node_, _NodeJS_, or similar variants.
+  * For the executable, _`node`_ is acceptable.
 
-* When referring to a version of Node.js in prose, use _Node.js_ and the version
-  number. Do not prefix the version number with _v_ in prose. This is to avoid
-  confusion about whether _v8_ refers to Node.js 8.x or the V8 JavaScript
-  engine.
-  <!-- lint enable prohibited-strings remark-lint-->
+### 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_
-* [Use sentence-style capitalization for headings][].
 
-See also API documentation structure overview in [doctools README][].
+<!-- lint enable prohibited-strings remark-lint-->
+
+For topics not addressed here, please consult the [Microsoft Writing Style Guide][].
 
-For topics not covered here, refer to the [Microsoft Writing Style Guide][].
+***
 
-[Be direct]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences
-[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
-[Microsoft Writing Style Guide]: https://docs.microsoft.com/en-us/style-guide/welcome/
-[Use US spelling]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
-[Use sentence-style capitalization for headings]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings
-[Use serial commas]: https://docs.microsoft.com/en-us/style-guide/punctuation/commas
+[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
-[doctools README]: ../tools/doc/README.md
-[info string]: https://github.github.com/gfm/#info-string
-[language]: https://github.com/highlightjs/highlight.js/blob/HEAD/SUPPORTED_LANGUAGES.md
 [plugin]: https://editorconfig.org/#download
+[serial commas]: https://learn.microsoft.com/en-us/style-guide/punctuation/commas
