11cb0ef41Sopenharmony_ci# Documentation style guide 21cb0ef41Sopenharmony_ci 31cb0ef41Sopenharmony_ciThis style guide helps us create organized and easy-to-read documentation. It 41cb0ef41Sopenharmony_ciprovides guidelines for organization, spelling, formatting, and more. 51cb0ef41Sopenharmony_ci 61cb0ef41Sopenharmony_ciThese are guidelines rather than strict rules. Content is more important than 71cb0ef41Sopenharmony_ciformatting. You do not need to learn the entire style guide before contributing 81cb0ef41Sopenharmony_cito documentation. Someone can always edit your material later to conform with 91cb0ef41Sopenharmony_cithis guide. 101cb0ef41Sopenharmony_ci 111cb0ef41Sopenharmony_ci* Documentation is in markdown files with names formatted as 121cb0ef41Sopenharmony_ci `lowercase-with-dashes.md`. 131cb0ef41Sopenharmony_ci * Use an underscore in the filename only if the underscore is part of the 141cb0ef41Sopenharmony_ci topic name (e.g., `child_process`). 151cb0ef41Sopenharmony_ci * Some files, such as top-level markdown files, are exceptions. 161cb0ef41Sopenharmony_ci* Documents should be word-wrapped at 80 characters. 171cb0ef41Sopenharmony_ci* `.editorconfig` describes the preferred formatting. 181cb0ef41Sopenharmony_ci * A [plugin][] is available for some editors to apply these rules. 191cb0ef41Sopenharmony_ci* Check changes to documentation with `make test-doc -j` or `vcbuild test-doc`. 201cb0ef41Sopenharmony_ci* [Use US spelling][]. 211cb0ef41Sopenharmony_ci* [Use serial commas][]. 221cb0ef41Sopenharmony_ci* Avoid first-person pronouns (_I_, _we_). 231cb0ef41Sopenharmony_ci * Exception: _we recommend foo_ is preferable to _foo is recommended_. 241cb0ef41Sopenharmony_ci* Use gender-neutral pronouns and gender-neutral plural nouns. 251cb0ef41Sopenharmony_ci * OK: _they_, _their_, _them_, _folks_, _people_, _developers_ 261cb0ef41Sopenharmony_ci * NOT OK: _his_, _hers_, _him_, _her_, _guys_, _dudes_ 271cb0ef41Sopenharmony_ci* When combining wrapping elements (parentheses and quotes), place terminal 281cb0ef41Sopenharmony_ci punctuation: 291cb0ef41Sopenharmony_ci * Inside the wrapping element if the wrapping element contains a complete 301cb0ef41Sopenharmony_ci clause. 311cb0ef41Sopenharmony_ci * Outside of the wrapping element if the wrapping element contains only a 321cb0ef41Sopenharmony_ci fragment of a clause. 331cb0ef41Sopenharmony_ci* Documents must start with a level-one heading. 341cb0ef41Sopenharmony_ci* Prefer affixing links (`[a link][]`) to inlining links 351cb0ef41Sopenharmony_ci (`[a link](http://example.com)`). 361cb0ef41Sopenharmony_ci* When documenting APIs, update the YAML comment associated with the API as 371cb0ef41Sopenharmony_ci appropriate. This is especially true when introducing or deprecating an API. 381cb0ef41Sopenharmony_ci* When documenting APIs, every function should have a usage example or 391cb0ef41Sopenharmony_ci link to an example that uses the function. 401cb0ef41Sopenharmony_ci* For code blocks: 411cb0ef41Sopenharmony_ci * Use [language][]-aware fences. (<code>\`\`\`js</code>) 421cb0ef41Sopenharmony_ci 431cb0ef41Sopenharmony_ci * For the [info string][], use one of the following. 441cb0ef41Sopenharmony_ci 451cb0ef41Sopenharmony_ci | Meaning | Info string | 461cb0ef41Sopenharmony_ci | ------------- | ------------ | 471cb0ef41Sopenharmony_ci | Bash | `bash` | 481cb0ef41Sopenharmony_ci | C | `c` | 491cb0ef41Sopenharmony_ci | C++ | `cpp` | 501cb0ef41Sopenharmony_ci | CoffeeScript | `coffee` | 511cb0ef41Sopenharmony_ci | Diff | `diff` | 521cb0ef41Sopenharmony_ci | HTTP | `http` | 531cb0ef41Sopenharmony_ci | JavaScript | `js` | 541cb0ef41Sopenharmony_ci | JSON | `json` | 551cb0ef41Sopenharmony_ci | Markdown | `markdown` | 561cb0ef41Sopenharmony_ci | Plaintext | `text` | 571cb0ef41Sopenharmony_ci | Powershell | `powershell` | 581cb0ef41Sopenharmony_ci | R | `r` | 591cb0ef41Sopenharmony_ci | Shell Session | `console` | 601cb0ef41Sopenharmony_ci 611cb0ef41Sopenharmony_ci If one of your language-aware fences needs an info string that is not 621cb0ef41Sopenharmony_ci already on this list, you may use `text` until the grammar gets added to 631cb0ef41Sopenharmony_ci [`remark-preset-lint-node`][]. 641cb0ef41Sopenharmony_ci 651cb0ef41Sopenharmony_ci * Code need not be complete. Treat code blocks as an illustration or aid to 661cb0ef41Sopenharmony_ci your point, not as complete running programs. If a complete running program 671cb0ef41Sopenharmony_ci is necessary, include it as an asset in `assets/code-examples` and link to 681cb0ef41Sopenharmony_ci it. 691cb0ef41Sopenharmony_ci* When using underscores, asterisks, and backticks, please use 701cb0ef41Sopenharmony_ci backslash-escaping: `\_`, `\*`, and ``\` ``. 711cb0ef41Sopenharmony_ci* Constructors should use PascalCase. 721cb0ef41Sopenharmony_ci* Instances should use camelCase. 731cb0ef41Sopenharmony_ci* Denote methods with parentheses: `socket.end()` instead of `socket.end`. 741cb0ef41Sopenharmony_ci* Function arguments or object properties should use the following format: 751cb0ef41Sopenharmony_ci * ``* `name` {type|type2} Optional description. **Default:** `value`.`` 761cb0ef41Sopenharmony_ci <!--lint disable maximum-line-length remark-lint--> 771cb0ef41Sopenharmony_ci * For example: <code>\* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code> 781cb0ef41Sopenharmony_ci <!--lint enable maximum-line-length remark-lint--> 791cb0ef41Sopenharmony_ci * The `type` should refer to a Node.js type or a [JavaScript type][]. 801cb0ef41Sopenharmony_ci* Function returns should use the following format: 811cb0ef41Sopenharmony_ci * <code>\* Returns: {type|type2} Optional description.</code> 821cb0ef41Sopenharmony_ci * E.g. <code>\* Returns: {AsyncHook} A reference to `asyncHook`.</code> 831cb0ef41Sopenharmony_ci* Use official styling for capitalization in products and projects. 841cb0ef41Sopenharmony_ci * OK: JavaScript, Google's V8 851cb0ef41Sopenharmony_ci <!--lint disable prohibited-strings remark-lint--> 861cb0ef41Sopenharmony_ci * NOT OK: Javascript, Google's v8 871cb0ef41Sopenharmony_ci* Use _Node.js_ and not _Node_, _NodeJS_, or similar variants. 881cb0ef41Sopenharmony_ci <!-- lint enable prohibited-strings remark-lint--> 891cb0ef41Sopenharmony_ci * When referring to the executable, _`node`_ is acceptable. 901cb0ef41Sopenharmony_ci* [Be direct][]. 911cb0ef41Sopenharmony_ci 921cb0ef41Sopenharmony_ci<!-- lint disable prohibited-strings remark-lint--> 931cb0ef41Sopenharmony_ci 941cb0ef41Sopenharmony_ci* When referring to a version of Node.js in prose, use _Node.js_ and the version 951cb0ef41Sopenharmony_ci number. Do not prefix the version number with _v_ in prose. This is to avoid 961cb0ef41Sopenharmony_ci confusion about whether _v8_ refers to Node.js 8.x or the V8 JavaScript 971cb0ef41Sopenharmony_ci engine. 981cb0ef41Sopenharmony_ci <!-- lint enable prohibited-strings remark-lint--> 991cb0ef41Sopenharmony_ci * OK: _Node.js 14.x_, _Node.js 14.3.1_ 1001cb0ef41Sopenharmony_ci * NOT OK: _Node.js v14_ 1011cb0ef41Sopenharmony_ci* [Use sentence-style capitalization for headings][]. 1021cb0ef41Sopenharmony_ci 1031cb0ef41Sopenharmony_ciSee also API documentation structure overview in [doctools README][]. 1041cb0ef41Sopenharmony_ci 1051cb0ef41Sopenharmony_ciFor topics not covered here, refer to the [Microsoft Writing Style Guide][]. 1061cb0ef41Sopenharmony_ci 1071cb0ef41Sopenharmony_ci[Be direct]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences 1081cb0ef41Sopenharmony_ci[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types 1091cb0ef41Sopenharmony_ci[Microsoft Writing Style Guide]: https://docs.microsoft.com/en-us/style-guide/welcome/ 1101cb0ef41Sopenharmony_ci[Use US spelling]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words 1111cb0ef41Sopenharmony_ci[Use sentence-style capitalization for headings]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings 1121cb0ef41Sopenharmony_ci[Use serial commas]: https://docs.microsoft.com/en-us/style-guide/punctuation/commas 1131cb0ef41Sopenharmony_ci[`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node 1141cb0ef41Sopenharmony_ci[doctools README]: ../tools/doc/README.md 1151cb0ef41Sopenharmony_ci[info string]: https://github.github.com/gfm/#info-string 1161cb0ef41Sopenharmony_ci[language]: https://github.com/highlightjs/highlight.js/blob/HEAD/SUPPORTED_LANGUAGES.md 1171cb0ef41Sopenharmony_ci[plugin]: https://editorconfig.org/#download 118