[Django] #35347: Clarify choice_set function in tutorial 2

[Django]

#35347: Clarify choice_set function in tutorial 2
------------------------------------------------+--------------------------
Reporter: AntWarden81 | Owner: nobody
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.0
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
------------------------------------------------+--------------------------
[Tutorial 2](https://docs.djangoproject.com/en/5.0/intro/tutorial02/)
introduces usage of the function `choice_set`, generated from the foreign
key to Question in the Choice object. However, the tutorial does not
specify where this function comes from or why it is created.

Adding a short blurb in the comments of the code block will clarify this
and explain how `choice_set` is created.
--
Ticket URL: <https://code.djangoproject.com/ticket/35347>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35347: Clarify choice_set function in tutorial 2

-------------------------------------+-------------------------------------
Reporter: AntWarden81 | Owner: nobody
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by AntWarden81):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:1>

[Django]

#35347: Clarify choice_set function in tutorial 2
-------------------------------------+-------------------------------------

Reporter: Lang Tran | Owner: nobody
Type: | Status: closed

Cleanup/optimization |
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:

| worksforme

Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* resolution: => worksforme
* status: assigned => closed

Comment:

The clarification is already present in the docs:

> Django creates a set to hold the "other side" of a ForeignKey relation
(e.g. a question's choice) which can be accessed via the API.

which says almost the same of what's proposed in the PR, but it's in the
same paragraph where the next steps are explained as a meaningful unit.
I'm not sure this should be changed, would you have more details on why
the above may not be sufficient?
--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:2>

[Django]

#35347: Clarify choice_set function in tutorial 2
-------------------------------------+-------------------------------------
Reporter: Lang Tran | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
| worksforme
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Lang Tran):

Going through the tutorial as a relative newcomer to Django I had trouble
investigating on my own how and where `choice_set` came from- now that you
point out the prior paragraph in detail, that makes sense, but I think it
would at least be helpful if we were to explicitly mention `choice_set`
even in that paragraph as a method created from the related object set. I
have personally found that when it comes to these autogenerated methods
based on some existing member the convention around what they're called,
how they're named, etc can be a bit murky unless explicitly called out.
--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:3>

[Django]

#35347: Clarify choice_set function in tutorial 2

--------------------------------------+------------------------------------

Reporter: Lang Tran | Owner: nobody

Type: Cleanup/optimization | Status: new

Component: Documentation | Version: 5.0
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* resolution: worksforme =>
* stage: Unreviewed => Accepted
* status: closed => new

Comment:

Thank you Lang for your response. I can see how by not mentioning
`choice_set`, we are adding an extra interpretation burden to the reader.

I'm happy to review a PR that adds that clarification, would you like to
re-purpose your previous PR? I'll re-open the ticket and the GitHub PR.
--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:4>

[Django]

#35347: Clarify choice_set function in tutorial 2

-------------------------------------+-------------------------------------
Reporter: Lang Tran | Owner: Lang Tran
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* owner: nobody => Lang Tran
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:5>

[Django]

#35347: Clarify choice_set function in tutorial 2
-------------------------------------+-------------------------------------
Reporter: Lang Tran | Owner: Lang Tran
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:6>

[Django]

#35347: Clarify choice_set function in tutorial 2
-------------------------------------+-------------------------------------
Reporter: Lang Tran | Owner: Lang Tran
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Tim Graham):

I doubt it's a common source of confusion. "Django creates a set... which
can be accessed via the API." does all but name the set. We could say
something like, "Django creates a choice_set attribute on Question
instances..." but it feels a bit unnecessary when example usage follows
two lines later.
--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:7>

[Django]

#35347: Clarify choice_set function in tutorial 2
-------------------------------------+-------------------------------------
Reporter: Lang Tran | Owner: Lang Tran
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Replying to [comment:7 Tim Graham]:

> I doubt it's a common source of confusion. "Django creates a set...
which can be accessed via the API." does all but name the set. We could
say something like, "Django creates a choice_set attribute on Question
instances..." but it feels a bit unnecessary when example usage follows
two lines later.

My understanding from the original report is that for someone new to
Django, it's not easy to make the connection that "''the set''" is
actually named `choice_set`. I know both things have the word "set" in it,
but I fear we may be too involved already in the project to not see the
connection (but newcomers may easily miss it).

I remember when I was learning Django, and seeing references to the
magical `something_set` attribute, and given my lack of experience and the
inevitable language barrier, I assume it to be a "weirdly named thing that
was like that just because a core dev did not like plurals" and not
because `_set` actually meant "''the set of [related] somethings''". More
so, when you read the tutorial in another language, "set" could be
translated to the proper term in that language so the connection is quite
challenging to be made, or worse, is not translated at all (because it's a
code comment) and the explanation is totally missed if the reader does not
understand English!
--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:8>

[Django]

#35347: Clarify choice_set function in tutorial 2
-------------------------------------+-------------------------------------
Reporter: Lang Tran | Owner: Lang Tran
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Lang Tran):

That was pretty much my experience going through the tutorial. The link
between `choice_set` and "the set" wasn't explicit enough for me to make
the connection, particularly when you're skimming comments as people
typically do. Another benefit is that if we explicitly mention it within
the comment then if somebody is ctrl+f-ing through the docs then they'll
see it mentioned in the comment and be able to make the connection.
--
Ticket URL: <https://code.djangoproject.com/ticket/35347#comment:9>