doc: improve formatting of STYLE_GUIDE.md

aqrln · MylesBorins · commit 079b04e58d2e · 2017-07-17T11:58:44.000-04:00
* Wrap text at 80 characters. * Use periods consistently. PR-URL: #13135 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Michael Dawson <mhdawson@ibm.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md
@@ -1,29 +1,30 @@
 # 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.
 * American English spelling is preferred. "Capitalize" vs. "Capitalise",
   "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"
-    * **NOT OK**: "his", "hers", "him", "her", "guys", "dudes".
+    * **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
@@ -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 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
