Skip to content

Commit 48d7a5b

Browse files
committed
minor #11685 Added a section about belittling words to the documentation standars (Toflar)
This PR was squashed before being merged into the 3.4 branch (closes #11685). Discussion ---------- Added a section about belittling words to the documentation standars We already got rid of loads of these words as initiated by symfony/diversity#9. However, I couldn't see this was mentioned anywhere in the docs yet so I tried to fix this 😄 Commits ------- edad658 Added a section about belittling words to the documentation standars
2 parents 9993814 + edad658 commit 48d7a5b

File tree

1 file changed

+18
-0
lines changed

1 file changed

+18
-0
lines changed

contributing/documentation/standards.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,24 @@ In addition, documentation follows these rules:
175175
* his or hers, use theirs
176176
* himself or herself, use themselves
177177

178+
* **Avoid belittling words**: People read documentation because they know very little about
179+
a specific topic or are even completely new to it. Things that seem "obvious" or "simple"
180+
for the person documenting it, can be the exact opposite for the reader. To make sure everybody
181+
feels comfortable when reading the documentation, try to avoid words like:
182+
183+
* simply
184+
* just
185+
* easy/easily
186+
* quick/quickly
187+
* of course
188+
* logically
189+
* clearly
190+
* obviously
191+
* merely
192+
* basically
193+
* trivial
194+
195+
178196
.. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
179197
.. _`Twig Coding Standards`: https://twig.symfony.com/doc/2.x/coding_standards.html
180198
.. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3

0 commit comments

Comments
 (0)