Merge pull request #32 from ipfs/guidelines

writing guidelines

docs-styleguide.md

@@ -2,6 +2,15 @@
 
 This is the documentation styleguide for our natural language descriptions used in the CLI tools, and elsewhere. Please conform to this spec.
 
+### TOC
+
+- [Code references](#code-references)
+  - [Acronyms](#acronyms)
+    - [Accepted forms:](#accepted-forms)
+- [Linguistic rules](#linguistic-rules)
+- [Ungendering](#ungendering)
+    - [Motivation](#motivation)
+
 ## Code references
 
 * Use `backticks` for every code example inside of a normal description. In the CLI, where you cannot use backticks, use 'single quotes' for commands.
@@ -21,3 +30,27 @@ This is the documentation styleguide for our natural language descriptions used
 
 * End phrases with a period. (Like that one).
 * Capitalize the first letter of a phrase or sentence.
+
+## Ungendering
+
+Avoid gendering in writing. Do not assume that the user/reader is of a certain gender.
+
+Do's:
+
+```
+Users install IPFS on their computers.
+Users can choose what to broadcast in the DHT.
+```
+
+Don'ts:
+
+```
+The user installs IPFS on his computer.
+User A can choose if the hash of her newly added file is broadcasted.
+```
+
+Established canon, like Alice and Bob for cryptography, can still be used in the gendered way.
+
+#### Motivation
+
+Avoiding gendering in community interaction has multiple benefits. Using a male or female pronoun alienates and unfairly prioritizes one gender in favor of another. For instance, saying "the user and his computer" may feel alienating to women, or vice versa. Luckily, in English, the pronoun 'their' can be used as both a singular and a plural form (cf. [Singular they](https://en.wikipedia.org/wiki/Singular_they)). Saying, "the user and their computer" is entirely acceptable and alleviates the issue.