Don't assume that things are "easy"/"obvious"/"simple" in the docs.

[Tobias Kunze]

Telling people in documentation that something is "easy" or "obvious" when it isn't to them is very frustrating: It implies that the reader should have a level of understanding they don't have, and doesn't add anything of value in return. There are many occurrences of more-or-less obvious instances of this pattern in the Django docs, and I'd like to reduce the occurrence of this pattern.

[Mariusz Felisiak]

Sound like a good idea.

​PR

Note: IMO we shouldn't backport this patch because it will create a huge amount of work for translators.

[Tapasweni Pathak]

Hello folks: I would like PRing for the ticket? Is the PR merged?

[Mariusz Felisiak]

Fix is already submitted, you should rather search for tickets without patches and owners.

[Mariusz Felisiak <felisiak.mariusz@…>]

In ed2d411:

Refs #30573 -- Noted to avoid "simple" & co. in Writing Style guide.

Co-authored-by: Tobias Kunze <r@…>

[Mariusz Felisiak <felisiak.mariusz@…>]

In dee22a0:

[2.2.x] Refs #30573 -- Noted to avoid "simple" & co. in Writing Style guide.

Co-authored-by: Tobias Kunze <r@…>

Backport of ed2d411aa84efc76baba3adf0d0f99df0e44ba57 from master

[Carlton Gibson]

Bar a last review of edits and a squash, this looks ready to go.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 4a954cf:

Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty.

This patch does not remove all occurrences of the words in question.
Rather, I went through all of the occurrences of the words listed
below, and judged if they a) suggested the reader had some kind of
knowledge/experience, and b) if they added anything of value (including
tone of voice, etc). I left most of the words alone. I looked at the
following words:

• simply/simple
• easy/easier/easiest
• obvious
• just
• merely
• straightforward
• ridiculous

Thanks to Carlton Gibson for guidance on how to approach this issue, and
to Tim Bell for providing the idea. But the enormous lion's share of
thanks go to Adam Johnson for his patient and helpful review.

[Mariusz Felisiak <felisiak.mariusz@…>]

In d17b3806:

Refs #30573 -- Rephrased "Of Course" and "Obvious(ly)" in documentation and comments.