Skip to content

Commit

Permalink
doc: improve style guide text
Browse files Browse the repository at this point in the history
* Specify that personal pronouns are OK in colloquial documentation
  rather than just pronouns. Pronouns are OK in all documentation. (For
  example, "it" is a pronoun and is acceptable in all types of
  documentation.) Specify "personal pronouns" for clarity.
* more colloquial -> colloquial
* like -> such as
* Remove "mass nouns" as no mass nouns are given as examples. Plural
  nouns seems to be what was meant, so use that instead.
* Repeat "gender-neutral" to make it clear that it refers to both terms
  and not merely the first term it appears before.
* Remove "non-comprehensive examples". Examples are, by definition,
  non-comprehensive. No need to announce that the examples are examples.
  It is obvious.

PR-URL: #19269
Reviewed-By: Luigi Pinca <[email protected]>
  • Loading branch information
Trott authored and BethGriggs committed Oct 16, 2018
1 parent 4bcdc1b commit 459690a
Showing 1 changed file with 2 additions and 3 deletions.
5 changes: 2 additions & 3 deletions doc/STYLE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,8 @@
"color" vs. "colour", etc.
* Use [serial commas][].
* Avoid personal pronouns in reference documentation ("I", "you", "we").
* Pronouns are acceptable in more colloquial documentation, like guides.
* Use gender-neutral pronouns and mass nouns. Non-comprehensive
examples:
* Personal pronouns are acceptable in colloquial documentation such as guides.
* Use gender-neutral pronouns and gender-neutral plural nouns.
* OK: "they", "their", "them", "folks", "people", "developers"
* NOT OK: "his", "hers", "him", "her", "guys", "dudes"
* When combining wrapping elements (parentheses and quotes), terminal
Expand Down

0 comments on commit 459690a

Please sign in to comment.