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