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.

1. General Guidelines
2. Writing Style
3. Punctuation
4. Document Structure
5. API Documentation
6. Code Blocks
7. Formatting
8. Product and Project 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.

• Wrap documents at 120 characters per line to enhance readability and version control.

• Follow the formatting rules specified in .editorconfig.
  • A plugin is available for some editors to enforce these rules.

• Validate documentation changes using make test-doc -j or vcbuild test-doc.

---

• Spelling: Use US spelling.
• Grammar: Use clear, concise language. Avoid unnecessary jargon.

• Serial Commas: Use serial commas for clarity.
  • Example: apples, oranges, and bananas

• Avoid first-person pronouns (I, we).
  • Exception: Use we recommend foo instead of foo is recommended.

• Use gender-neutral pronouns and plural nouns.
  • OK: they, their, them, folks, people, developers
  • NOT OK: his, hers, him, her, guys, dudes

• Use precise technical terms and avoid colloquialisms.
• Define any specialized terms or acronyms at first use.

---

• Place inside parentheses or quotes if the content is a complete clause.
• Place outside if the content is a fragment of a clause.

• Use double quotation marks for direct quotes.
• Use single quotation marks for quotes within quotes.

• Use colons to introduce lists or explanations.
• Use semicolons to link closely related independent clauses.

---

• Start documents with a level-one heading (#).
• Use subsequent headings (##, ###, etc.) to organize content hierarchically.

• Prefer reference-style links ([a link][]) over inline links ([a link](http://example.com)).

• Use bullet points for unordered lists and numbers for ordered lists.
• Keep list items parallel in structure.

• Use tables to present structured information clearly. Ensure they are readable in plain text.

---

• Update the YAML comments associated with the API, especially when introducing or deprecating an API.

• Provide a usage example or a link to an example for every function.

• Clearly describe parameters and return values, including types and defaults.
  • Example:

    * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.

---

• 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.

• Use comments to explain complex logic within code examples.
• Follow the standard commenting style of the respective language.

---

• Use backslash-escaping for underscores, asterisks, and backticks: \_, \*, \`.

• Constructors: Use PascalCase.
• Instances: Use camelCase.
• Methods: Indicate methods with parentheses: socket.end() instead of socket.end.

• Arguments:

  * `name` {type|type2} Optional description. **Default:** `value`.

  Example:

  * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.

• Returns:

  * Returns: {type|type2} Optional description.

  Example:

  * Returns: {AsyncHook} A reference to `asyncHook`.

---

• Use official capitalization for products and projects.
  • OK: JavaScript, Google's V8
  • NOT OK: Javascript, Google's v8

• Use Node.js instead of Node, NodeJS, or similar variants.
  • For the executable, node is acceptable.

• 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

For topics not addressed here, please consult the Microsoft Writing Style Guide.

---