1# Documentation style guide 2 3This style guide helps us create organized and easy-to-read documentation. It 4provides guidelines for organization, spelling, formatting, and more. 5 6These are guidelines rather than strict rules. Content is more important than 7formatting. You do not need to learn the entire style guide before contributing 8to documentation. Someone can always edit your material later to conform with 9this guide. 10 11* Documentation is in markdown files with names formatted as 12 `lowercase-with-dashes.md`. 13 * Use an underscore in the filename only if the underscore is part of the 14 topic name (e.g., `child_process`). 15 * Some files, such as top-level markdown files, are exceptions. 16* Documents should be word-wrapped at 80 characters. 17* `.editorconfig` describes the preferred formatting. 18 * A [plugin][] is available for some editors to apply these rules. 19* Check changes to documentation with `make test-doc -j` or `vcbuild test-doc`. 20* [Use US spelling][]. 21* [Use serial commas][]. 22* Avoid first-person pronouns (_I_, _we_). 23 * Exception: _we recommend foo_ is preferable to _foo is recommended_. 24* Use gender-neutral pronouns and gender-neutral plural nouns. 25 * OK: _they_, _their_, _them_, _folks_, _people_, _developers_ 26 * NOT OK: _his_, _hers_, _him_, _her_, _guys_, _dudes_ 27* When combining wrapping elements (parentheses and quotes), place terminal 28 punctuation: 29 * Inside the wrapping element if the wrapping element contains a complete 30 clause. 31 * Outside of the wrapping element if the wrapping element contains only a 32 fragment of a clause. 33* Documents must start with a level-one heading. 34* Prefer affixing links (`[a link][]`) to inlining links 35 (`[a link](http://example.com)`). 36* When documenting APIs, update the YAML comment associated with the API as 37 appropriate. This is especially true when introducing or deprecating an API. 38* When documenting APIs, every function should have a usage example or 39 link to an example that uses the function. 40* For code blocks: 41 * Use [language][]-aware fences. (<code>\`\`\`js</code>) 42 43 * For the [info string][], use one of the following. 44 45 | Meaning | Info string | 46 | ------------- | ------------ | 47 | Bash | `bash` | 48 | C | `c` | 49 | C++ | `cpp` | 50 | CoffeeScript | `coffee` | 51 | Diff | `diff` | 52 | HTTP | `http` | 53 | JavaScript | `js` | 54 | JSON | `json` | 55 | Markdown | `markdown` | 56 | Plaintext | `text` | 57 | Powershell | `powershell` | 58 | R | `r` | 59 | Shell Session | `console` | 60 61 If one of your language-aware fences needs an info string that is not 62 already on this list, you may use `text` until the grammar gets added to 63 [`remark-preset-lint-node`][]. 64 65 * Code need not be complete. Treat code blocks as an illustration or aid to 66 your point, not as complete running programs. If a complete running program 67 is necessary, include it as an asset in `assets/code-examples` and link to 68 it. 69* When using underscores, asterisks, and backticks, please use 70 backslash-escaping: `\_`, `\*`, and ``\` ``. 71* Constructors should use PascalCase. 72* Instances should use camelCase. 73* Denote methods with parentheses: `socket.end()` instead of `socket.end`. 74* Function arguments or object properties should use the following format: 75 * ``* `name` {type|type2} Optional description. **Default:** `value`.`` 76 <!--lint disable maximum-line-length remark-lint--> 77 * For example: <code>\* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code> 78 <!--lint enable maximum-line-length remark-lint--> 79 * The `type` should refer to a Node.js type or a [JavaScript type][]. 80* Function returns should use the following format: 81 * <code>\* Returns: {type|type2} Optional description.</code> 82 * E.g. <code>\* Returns: {AsyncHook} A reference to `asyncHook`.</code> 83* Use official styling for capitalization in products and projects. 84 * OK: JavaScript, Google's V8 85 <!--lint disable prohibited-strings remark-lint--> 86 * NOT OK: Javascript, Google's v8 87* Use _Node.js_ and not _Node_, _NodeJS_, or similar variants. 88 <!-- lint enable prohibited-strings remark-lint--> 89 * When referring to the executable, _`node`_ is acceptable. 90* [Be direct][]. 91 92<!-- lint disable prohibited-strings remark-lint--> 93 94* When referring to a version of Node.js in prose, use _Node.js_ and the version 95 number. Do not prefix the version number with _v_ in prose. This is to avoid 96 confusion about whether _v8_ refers to Node.js 8.x or the V8 JavaScript 97 engine. 98 <!-- lint enable prohibited-strings remark-lint--> 99 * OK: _Node.js 14.x_, _Node.js 14.3.1_ 100 * NOT OK: _Node.js v14_ 101* [Use sentence-style capitalization for headings][]. 102 103See also API documentation structure overview in [doctools README][]. 104 105For topics not covered here, refer to the [Microsoft Writing Style Guide][]. 106 107[Be direct]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences 108[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types 109[Microsoft Writing Style Guide]: https://docs.microsoft.com/en-us/style-guide/welcome/ 110[Use US spelling]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words 111[Use sentence-style capitalization for headings]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings 112[Use serial commas]: https://docs.microsoft.com/en-us/style-guide/punctuation/commas 113[`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node 114[doctools README]: ../tools/doc/README.md 115[info string]: https://github.github.com/gfm/#info-string 116[language]: https://github.com/highlightjs/highlight.js/blob/HEAD/SUPPORTED_LANGUAGES.md 117[plugin]: https://editorconfig.org/#download 118