Merge branch '3.4' into 4.2

javiereguiluz · javiereguiluz · commit 1e11b501c172 · 2019-06-07T11:07:27.000+02:00
* 3.4:
  Added a section about belittling words to the documentation standars
diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst
@@ -173,6 +173,24 @@ In addition, documentation follows these rules:
   * his or hers, use theirs
   * himself or herself, use themselves
 
+* **Avoid belittling words**: People read documentation because they know very
+  little about a specific topic or are even completely new to it. Things that
+  seem "obvious" or "simple" for the person documenting it, can be the exact
+  opposite for the reader. To make sure everybody feels comfortable when reading
+  the documentation, try to avoid words like:
+
+  * basically
+  * clearly
+  * easy/easily
+  * just
+  * logically
+  * merely
+  * obviously
+  * of course
+  * quick/quickly
+  * simply
+  * trivial
+
 .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
 .. _`Twig Coding Standards`: https://twig.symfony.com/doc/2.x/coding_standards.html
 .. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3
