Skip to content

Commit 823f0ce

Browse files
Trottrvagg
authored andcommitted
doc: revise Style Guide
Most important change here is to point people to the YAML material in the docs rather than the previous way we indicated versions that introduced or deprecated APIs. Remove contents about assets as we do not actually have any in the docs. Otherwise, a bunch of stylistic changes, mostly to keep things concise and direct. PR-URL: #26176 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Beth Griggs <Bethany.Griggs@uk.ibm.com>
1 parent cd10e25 commit 823f0ce

File tree

1 file changed

+20
-30
lines changed

1 file changed

+20
-30
lines changed

doc/STYLE_GUIDE.md

+20-30
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
11
# Style Guide
22

3-
* Documentation is written in markdown files with names formatted as
3+
* Documentation is in markdown files with names formatted as
44
`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`).
5+
* Use an underscore in the filename only if the underscore is part of the
6+
topic name (e.g., `child_process`).
77
* Some files, such as top-level markdown files, are exceptions.
88
* 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.
9+
* `.editorconfig` describes the preferred formatting.
10+
* A [plugin][] is available for some editors to apply these rules.
11+
* Check changes to documentation with `make lint-md`.
12+
* Use American English spelling.
1413
* OK: _capitalize_, _color_
1514
* NOT OK: _capitalise_, _colour_
1615
* Use [serial commas][].
@@ -19,39 +18,30 @@
1918
* Use gender-neutral pronouns and gender-neutral plural nouns.
2019
* OK: _they_, _their_, _them_, _folks_, _people_, _developers_
2120
* NOT OK: _his_, _hers_, _him_, _her_, _guys_, _dudes_
22-
* When combining wrapping elements (parentheses and quotes), terminal
23-
punctuation should be placed:
21+
* When combining wrapping elements (parentheses and quotes), place terminal
22+
punctuation:
2423
* Inside the wrapping element if the wrapping element contains a complete
25-
clause — a subject, verb, and an object.
24+
clause.
2625
* Outside of the wrapping element if the wrapping element contains only a
2726
fragment of a clause.
2827
* Documents must start with a level-one heading.
2928
* Prefer affixing links to inlining links — prefer `[a link][]` to
3029
`[a link](http://example.com)`.
31-
* When documenting APIs, note the version the API was introduced in at
32-
the end of the section. If an API has been deprecated, also note the first
33-
version that the API appeared deprecated in.
34-
* When using dashes, use [Em dashes][] ("—" or `Option+Shift+"-"` on macOS)
35-
surrounded by spaces, as per [The New York Times Manual of Style and Usage][].
36-
* Including assets:
37-
* If you wish to add an illustration or full program, add it to the
38-
appropriate sub-directory in the `assets/` dir.
39-
* Link to it like so: `[Asset](/assets/{subdir}/{filename})` for file-based
40-
assets, and `![Asset](/assets/{subdir}/{filename})` for image-based assets.
41-
* For illustrations, prefer SVG to other assets. When SVG is not feasible,
42-
please keep a close eye on the filesize of the asset you're introducing.
30+
* When documenting APIs, update the YAML comment associated with the API as
31+
appropriate. This is especially true when introducing or deprecating an API.
32+
* Use [Em dashes][] ("—" or `Option+Shift+"-"` on macOS) surrounded by spaces,
33+
as per [The New York Times Manual of Style and Usage][].
4334
* For code blocks:
4435
* Use language aware fences. ("```js")
45-
* Code need not be complete — treat code blocks as an illustration or aid to
36+
* Code need not be complete. Treat code blocks as an illustration or aid to
4637
your point, not as complete running programs. If a complete running program
4738
is necessary, include it as an asset in `assets/code-examples` and link to
4839
it.
49-
* When using underscores, asterisks, and backticks, please use proper escaping
50-
(`\_`, `\*` and ``\` `` instead of `_`, `*` and `` ` ``).
51-
* References to constructor functions should use PascalCase.
52-
* References to constructor instances should use camelCase.
53-
* References to methods should be used with parentheses: for example,
54-
`socket.end()` instead of `socket.end`.
40+
* When using underscores, asterisks, and backticks, please use
41+
backslash-escaping: `\_`, `\*`, and ``\` ``.
42+
* Constructors should use PascalCase.
43+
* Instances should use camelCase.
44+
* Denote methods with parentheses: `socket.end()` instead of `socket.end`.
5545
* Function arguments or object properties should use the following format:
5646
* ``` * `name` {type|type2} Optional description. **Default:** `value`. ```
5747
<!--lint disable maximum-line-length remark-lint-->

0 commit comments

Comments
 (0)