[Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs
Django
------------------------------------------------+--------------------------
Reporter: Tobias Kunze | Owner: nobody
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+--------------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/30573>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Tobias Kunze | Owner: nobody
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tobias Kunze):
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:1>
Django
--------------------------------------+------------------------------------
Reporter: Tobias Kunze | Owner: nobody
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* stage: Unreviewed => Accepted
Comment:
Sound like a good idea.
[https://github.com/django/django/pull/11482 PR]
Note: IMO we shouldn't backport this patch because it will create a huge
amount of work for translators.
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:2>
Django
--------------------------------------+------------------------------------
Reporter: Tobias Kunze | Owner: nobody
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by tapaswenipathak):
Hello folks: I would like PRing for the ticket? Is the PR merged?
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: Tobias Kunze | Owner: Tobias
Type: | Kunze
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* owner: nobody => Tobias Kunze
Comment:
Fix is already submitted, you should rather search for tickets without
patches and owners.
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Tobias Kunze | Owner: Tobias
Type: | Kunze
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"ed2d411aa84efc76baba3adf0d0f99df0e44ba57" ed2d411]:
{{{
#!CommitTicketReference repository=""
revision="ed2d411aa84efc76baba3adf0d0f99df0e44ba57"
Refs #30573 -- Noted to avoid "simple" & co. in Writing Style guide.
Co-authored-by: Tobias Kunze <r...@rixx.de>
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Tobias Kunze | Owner: Tobias
Type: | Kunze
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"dee22a024bcaa20d0f0c2592827b031a4f6b1fe7" dee22a0]:
{{{
#!CommitTicketReference repository=""
revision="dee22a024bcaa20d0f0c2592827b031a4f6b1fe7"
[2.2.x] Refs #30573 -- Noted to avoid "simple" & co. in Writing Style
guide.
Co-authored-by: Tobias Kunze <r...@rixx.de>
Backport of ed2d411aa84efc76baba3adf0d0f99df0e44ba57 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Tobias Kunze | Owner: Tobias
Type: | Kunze
Component: Documentation | Version: master
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Carlton Gibson):
* stage: Accepted => Ready for checkin
Comment:
Bar a last review of edits and a squash, this looks ready to go.
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Tobias Kunze | Owner: Tobias
Type: | Kunze
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak <felisiak.mariusz@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"4a954cfd11a5d034491f87fcbc920eb97a302bb3" 4a954cf]:
{{{
#!CommitTicketReference repository=""
revision="4a954cfd11a5d034491f87fcbc920eb97a302bb3"
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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Tobias Kunze | Owner: Tobias
Type: | Kunze
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"d17b380653da5f95885ce53468fe7aac60672841" d17b3806]:
{{{
#!CommitTicketReference repository=""
revision="d17b380653da5f95885ce53468fe7aac60672841"
Refs #30573 -- Rephrased "Of Course" and "Obvious(ly)" in documentation
and comments.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:9>