From 19efac21527c17db7e84edf6bc2607919992dab7 Mon Sep 17 00:00:00 2001 From: Alexey Orlenko Date: Sun, 21 May 2017 02:12:15 +0300 Subject: [PATCH 1/2] doc: improve formatting of STYLE_GUIDE.md * Wrap text at 80 characters. * Use periods consistently. --- doc/STYLE_GUIDE.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 0d3fc001073fcb..7eea046c60ee01 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -1,16 +1,17 @@ # Style Guide * Documents are written in markdown files. -* Those files should be written in **`lowercase-with-dashes.md`.** +* Those files should be written in **`lowercase-with-dashes.md`**. * Underscores in filenames are allowed only when they are present in the - topic the document will describe (e.g., `child_process`.) + topic the document will describe (e.g., `child_process`). * Filenames should be **lowercase**. * Some files, such as top-level markdown files, are exceptions. * Older files may use the `.markdown` extension. These may be ported to `.md` at will. **Prefer `.md` for all new documents.** * Documents should be word-wrapped at 80 characters. * The formatting described in `.editorconfig` is preferred. - * A [plugin][] is available for some editors to automatically apply these rules. + * A [plugin][] is available for some editors to automatically apply these + rules. * Mechanical issues, like spelling and grammar, should be identified by tools, insofar as is possible. If not caught by a tool, they should be pointed out by human reviewers. @@ -18,11 +19,11 @@ "color" vs. "colour", etc. * Though controversial, the [Oxford comma][] is preferred for clarity's sake. * Generally avoid personal pronouns in reference documentation ("I", "you", - "we".) + "we"). * Pronouns are acceptable in more colloquial documentation, like guides. * Use **gender-neutral pronouns** and **mass nouns**. Non-comprehensive examples: - * **OK**: "they", "their", "them", "folks", "people", "developers", "cats" + * **OK**: "they", "their", "them", "folks", "people", "developers", "cats". * **NOT OK**: "his", "hers", "him", "her", "guys", "dudes". * When combining wrapping elements (parentheses and quotes), terminal punctuation should be placed: @@ -54,10 +55,12 @@ your point, not as complete running programs. If a complete running program is necessary, include it as an asset in `assets/code-examples` and link to it. -* When using underscores, asterisks and backticks please use proper escaping (**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**) -* References to constructor functions should use PascalCase -* References to constructor instances should be camelCased -* References to methods should be used with parentheses: `socket.end()` instead of `socket.end` +* When using underscores, asterisks and backticks please use proper escaping + (**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**). +* References to constructor functions should use PascalCase. +* References to constructor instances should be camelCased. +* References to methods should be used with parentheses: `socket.end()` instead + of `socket.end`. [plugin]: http://editorconfig.org/#download [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma From 43a021b627988a97fccdb2bfccfd5cac6ef24779 Mon Sep 17 00:00:00 2001 From: Alexey Orlenko Date: Mon, 22 May 2017 03:42:19 +0300 Subject: [PATCH 2/2] squash! address feedback --- doc/STYLE_GUIDE.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 7eea046c60ee01..56d4b98ee92033 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -23,8 +23,8 @@ * Pronouns are acceptable in more colloquial documentation, like guides. * Use **gender-neutral pronouns** and **mass nouns**. Non-comprehensive examples: - * **OK**: "they", "their", "them", "folks", "people", "developers", "cats". - * **NOT OK**: "his", "hers", "him", "her", "guys", "dudes". + * **OK**: "they", "their", "them", "folks", "people", "developers", "cats" + * **NOT OK**: "his", "hers", "him", "her", "guys", "dudes" * When combining wrapping elements (parentheses and quotes), terminal punctuation should be placed: * Inside the wrapping element if the wrapping element contains a complete @@ -55,12 +55,12 @@ your point, not as complete running programs. If a complete running program is necessary, include it as an asset in `assets/code-examples` and link to it. -* When using underscores, asterisks and backticks please use proper escaping +* When using underscores, asterisks, and backticks, please use proper escaping (**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**). * References to constructor functions should use PascalCase. -* References to constructor instances should be camelCased. -* References to methods should be used with parentheses: `socket.end()` instead - of `socket.end`. +* References to constructor instances should use camelCase. +* References to methods should be used with parentheses: for example, + `socket.end()` instead of `socket.end`. [plugin]: http://editorconfig.org/#download [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma