[Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

[Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs

Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs
------------------------------------------------+--------------------------
               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.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/047.0cc8e72c57465460e0e1c60c93c92b37%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs

Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs
-------------------------------------+-------------------------------------
     Reporter:  Tobias Kunze         |                    Owner:  nobody
         Type:                       |                   Status:  assigned
  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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.f0127c35b3eb46632caaac53f2aa3d6a%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs. (was: Don't assume that things are "easy"/"obvious"/"simple" in the docs)

Django
In reply to this post by Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.
--------------------------------------+------------------------------------
     Reporter:  Tobias Kunze          |                    Owner:  nobody
         Type:  Cleanup/optimization  |                   Status:  assigned
    Component:  Documentation         |                  Version:  master
     Severity:  Normal                |               Resolution:
     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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.dce8009186f4259d90ce78659bb53be2%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.

Django
In reply to this post by Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.
--------------------------------------+------------------------------------
     Reporter:  Tobias Kunze          |                    Owner:  nobody
         Type:  Cleanup/optimization  |                   Status:  assigned
    Component:  Documentation         |                  Version:  master
     Severity:  Normal                |               Resolution:
     Keywords:                        |             Triage Stage:  Accepted
    Has patch:  1                     |      Needs documentation:  0
  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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.6dc58b3bbc77acac9281d3f4f57773a8%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.

Django
In reply to this post by Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.
-------------------------------------+-------------------------------------
     Reporter:  Tobias Kunze         |                    Owner:  Tobias
         Type:                       |  Kunze
  Cleanup/optimization               |                   Status:  assigned
    Component:  Documentation        |                  Version:  master
     Severity:  Normal               |               Resolution:
     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):

 * 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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.a5acbae7f1b7791107c0b327d17a60f3%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.

Django
In reply to this post by Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.
-------------------------------------+-------------------------------------
     Reporter:  Tobias Kunze         |                    Owner:  Tobias
         Type:                       |  Kunze
  Cleanup/optimization               |                   Status:  assigned
    Component:  Documentation        |                  Version:  master
     Severity:  Normal               |               Resolution:
     Keywords:                       |             Triage Stage:  Accepted
    Has patch:  1                    |      Needs documentation:  0
  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 <[hidden email]>
 }}}

--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:5>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.2ddc4cb747e363c883f4e969e5e8fd53%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.

Django
In reply to this post by Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.
-------------------------------------+-------------------------------------
     Reporter:  Tobias Kunze         |                    Owner:  Tobias
         Type:                       |  Kunze
  Cleanup/optimization               |                   Status:  assigned
    Component:  Documentation        |                  Version:  master
     Severity:  Normal               |               Resolution:
     Keywords:                       |             Triage Stage:  Accepted
    Has patch:  1                    |      Needs documentation:  0
  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 <[hidden email]>

 Backport of ed2d411aa84efc76baba3adf0d0f99df0e44ba57 from master
 }}}

--
Ticket URL: <https://code.djangoproject.com/ticket/30573#comment:6>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.1575fbe8f3f20583424873ad3bef4c5a%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.

Django
In reply to this post by Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.
-------------------------------------+-------------------------------------
     Reporter:  Tobias Kunze         |                    Owner:  Tobias
         Type:                       |  Kunze
  Cleanup/optimization               |                   Status:  assigned
    Component:  Documentation        |                  Version:  master
     Severity:  Normal               |               Resolution:
     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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.51dec9499f3426ac401146174dde2782%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.

Django
In reply to this post by Django
#30573: Don't assume that things are "easy"/"obvious"/"simple" in the docs.
-------------------------------------+-------------------------------------
     Reporter:  Tobias Kunze         |                    Owner:  Tobias
         Type:                       |  Kunze
  Cleanup/optimization               |                   Status:  closed
    Component:  Documentation        |                  Version:  master
     Severity:  Normal               |               Resolution:  fixed
     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 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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

--
You received this message because you are subscribed to the Google Groups "Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/062.ea470e6d935a2c2e7cbbbf63914a4098%40djangoproject.com.