From 2d3e762e1e43d6710ee43a97becf426820d57602 Mon Sep 17 00:00:00 2001 From: Yanick Witschi Date: Thu, 6 Jun 2019 10:13:22 +0200 Subject: [PATCH 1/2] Added a section about belittling words to the documentation standars --- contributing/documentation/standards.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 05083334eb9..f16b4f7b1db 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -175,6 +175,27 @@ In addition, documentation follows these rules: * his or hers, use theirs * himself or herself, use themselves +Moreover, we try to avoid belittling words as much as possible. Usually, the people +that write documentation write about a topic they are very familiar with. Thus, they +tend to include words like "simply" or "obviously" as things may seem simple or obvious +to them. However, the future reader is going to read the documentation because they +know very little about a specific topic or are even completely new to it which means +they might feel the exact opposite. +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 From 8a6daf4b276197d1324482349fb421596886124c Mon Sep 17 00:00:00 2001 From: Yanick Witschi Date: Thu, 6 Jun 2019 10:56:07 +0200 Subject: [PATCH 2/2] Restructured the text --- contributing/documentation/standards.rst | 37 +++++++++++------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index f16b4f7b1db..1c656822ea5 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -175,26 +175,23 @@ In addition, documentation follows these rules: * his or hers, use theirs * himself or herself, use themselves -Moreover, we try to avoid belittling words as much as possible. Usually, the people -that write documentation write about a topic they are very familiar with. Thus, they -tend to include words like "simply" or "obviously" as things may seem simple or obvious -to them. However, the future reader is going to read the documentation because they -know very little about a specific topic or are even completely new to it which means -they might feel the exact opposite. -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 +* **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