nodejs/doc/guides/doc-style-guide.md

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 ([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.
• 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.
  • The type should refer to a Node.js type or a JavaScript type.
• 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.