diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 05083334eb9..1c656822ea5 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -175,6 +175,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: + + * simply + * just + * easy/easily + * quick/quickly + * of course + * logically + * clearly + * obviously + * merely + * basically + * 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