1# Style Guide 2 3* Documentation is written in markdown files with names formatted as 4 `lowercase-with-dashes.md`. 5 * Underscores in filenames are allowed only when they are present in the 6 topic the document will describe (e.g. `child_process`). 7 * Some files, such as top-level markdown files, are exceptions. 8* Documents should be word-wrapped at 80 characters. 9* The formatting described in `.editorconfig` is preferred. 10 * A [plugin][] is available for some editors to automatically apply these 11 rules. 12* Changes to documentation should be checked with `make lint-md`. 13* American English spelling is preferred. "Capitalize" vs. "Capitalise", 14 "color" vs. "colour", etc. 15* Use [serial commas][]. 16* Avoid personal pronouns in reference documentation ("I", "you", "we"). 17 * Personal pronouns are acceptable in colloquial documentation such as guides. 18 * Use gender-neutral pronouns and gender-neutral plural nouns. 19 * OK: "they", "their", "them", "folks", "people", "developers" 20 * NOT OK: "his", "hers", "him", "her", "guys", "dudes" 21* When combining wrapping elements (parentheses and quotes), terminal 22 punctuation should be placed: 23 * Inside the wrapping element if the wrapping element contains a complete 24 clause — a subject, verb, and an object. 25 * Outside of the wrapping element if the wrapping element contains only a 26 fragment of a clause. 27* Documents must start with a level-one heading. 28* Prefer affixing links to inlining links — prefer `[a link][]` to 29 `[a link](http://example.com)`. 30* When documenting APIs, note the version the API was introduced in at 31 the end of the section. If an API has been deprecated, also note the first 32 version that the API appeared deprecated in. 33* When using dashes, use [Em dashes][] ("—" or `Option+Shift+"-"` on macOS) 34 surrounded by spaces, as per [The New York Times Manual of Style and Usage][]. 35* Including assets: 36 * If you wish to add an illustration or full program, add it to the 37 appropriate sub-directory in the `assets/` dir. 38 * Link to it like so: `[Asset](/assets/{subdir}/{filename})` for file-based 39 assets, and `![Asset](/assets/{subdir}/{filename})` for image-based assets. 40 * For illustrations, prefer SVG to other assets. When SVG is not feasible, 41 please keep a close eye on the filesize of the asset you're introducing. 42* For code blocks: 43 * Use language aware fences. ("```js") 44 * Code need not be complete — treat code blocks as an illustration or aid to 45 your point, not as complete running programs. If a complete running program 46 is necessary, include it as an asset in `assets/code-examples` and link to 47 it. 48* When using underscores, asterisks, and backticks, please use proper escaping 49 (`\_`, `\*` and ``\` `` instead of `_`, `*` and `` ` ``). 50* References to constructor functions should use PascalCase. 51* References to constructor instances should use camelCase. 52* References to methods should be used with parentheses: for example, 53 `socket.end()` instead of `socket.end`. 54* Function arguments or object properties should use the following format: 55 * ``` * `name` {type|type2} Optional description. **Default:** `value`. ``` 56 <!--lint disable maximum-line-length remark-lint--> 57 * For example: <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code> 58 <!--lint enable maximum-line-length remark-lint--> 59 * The `type` should refer to a Node.js type or a [JavaScript type][]. 60* Function returns should use the following format: 61 * <code>* Returns: {type|type2} Optional description.</code> 62 * E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code> 63* Use official styling for capitalization in products and projects. 64 * OK: JavaScript, Google's V8 65 <!--lint disable prohibited-strings remark-lint--> 66 * NOT OK: Javascript, Google's v8 67 <!-- lint enable prohibited-strings remark-lint--> 68* Use _Node.js_ and not _Node_, _NodeJS_, or similar variants. 69 * When referring to the executable, _`node`_ is acceptable. 70 71See also API documentation structure overview in [doctools README][]. 72 73[Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash 74[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types 75[serial commas]: https://en.wikipedia.org/wiki/Serial_comma 76[The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage 77[plugin]: http://editorconfig.org/#download 78[doctools README]: ../tools/doc/README.md 79