Documentation style guide

• Use US spelling.
• Use serial commas.
• 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.
  • 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, every function should have a usage example or link to an example that uses the function.

• For code blocks:

  • Use language-aware fences. (```js)

  • 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

  • Code need not be complete. Treat code blocks as an illustration or aid to your point, not as complete running programs.

• 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][]> Description. **Default:** `value`.
  • The description and default are both optional.
  • The type should be affixed links to an internal type or a JavaScript type.
    • When using unknown as a type, use TypeScript's docs on unknown.

  • E.g.

    - `byteOffset` <[number][]> Index of first byte to expose. **Default:** `0`.
    
    <!-- later on... -->
    
    [number]: https://developer.mozilla.org/en-US/docs/Glossary/Number
    

• Function returns should use the following format:

  • - Returns: <[type][]|[type2][]> Optional description.

  • E.g.

    - Returns: <[SerializedMessage][]> The message, serialized and ready to be passed to chrome.
    
    <!-- later on... -->
    
    [serializedmessage]: ./message.md#serializedmessage
    

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