Style 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 lint-md.
  • Use American English spelling.
    • OK: capitalize, color
    • NOT OK: capitalise, colour
  • Use serial commas.
  • Avoid personal pronouns (I, you, we) in reference documentation.
    • Personal pronouns are acceptable in colloquial documentation such as guides.
    • Use gender-neutral pronouns and gender-neutral 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 to inlining links — prefer [a link][] to [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.
  • Use Em dashes (“—” or Option+Shift+"-" on macOS) surrounded by spaces, as per The New York Times Manual of Style and Usage.
  • For code blocks:
    • Use language aware fences. (“```js”)
    • 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`.
    • For example: * byteOffset {integer} Index of first byte to expose. Default: 0.
  • Function returns should use the following format:
    • * Returns: {type|type2} Optional description.
    • E.g. * Returns: {AsyncHook} A reference to asyncHook.
  • Use official styling for capitalization in products and projects.
    • OK: JavaScript, Google's V8
    • NOT OK: Javascript, Google's v8
  • Use Node.js and not Node, NodeJS, or similar variants.
    • When referring to the executable, node is acceptable.
  • Be direct.
    • OK: The return value is a string.
    • NOT OK: It is important to note that, in all cases, the return value will be a string regardless.

See also API documentation structure overview in doctools README.