Opened 7 months ago

Closed 7 months ago

Last modified 7 months ago

#35347 closed Cleanup/optimization (fixed)

Clarify choice_set attribute in tutorial 2

Reported by: Lang Tran Owned by: Lang Tran
Component: Documentation Version: 5.0
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

[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.

Change History (12)

comment:1 by Lang Tran, 7 months ago

Has patch: set

comment:2 by Natalia Bidart, 7 months ago

Resolution: worksforme
Status: assignedclosed

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?

comment:3 by Lang Tran, 7 months ago

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.

comment:4 by Natalia Bidart, 7 months ago

Resolution: worksforme
Status: closednew
Triage Stage: UnreviewedAccepted

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.

comment:5 by Natalia Bidart, 7 months ago

Owner: changed from nobody to Lang Tran
Status: newassigned

comment:6 by Natalia Bidart, 7 months ago

Patch needs improvement: set

comment:7 by Tim Graham, 7 months ago

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.

in reply to:  7 comment:8 by Natalia Bidart, 7 months ago

Replying to 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!

comment:9 by Lang Tran, 7 months ago

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.

comment:10 by Tim Graham, 7 months ago

Patch needs improvement: unset
Summary: Clarify choice_set function in tutorial 2Clarify choice_set attribute in tutorial 2
Triage Stage: AcceptedReady for checkin

comment:11 by GitHub <noreply@…>, 7 months ago

Resolution: fixed
Status: assignedclosed

In e279c72:

Fixed #35347 -- Clarified choice_set attribute in tutorial 2.

comment:12 by Natalia <124304+nessita@…>, 7 months ago

In 88c0a66f:

[5.0.x] Fixed #35347 -- Clarified choice_set attribute in tutorial 2.

Backport of e279c724c12b4edc808cd208245dfa6d10505879 from main

Note: See TracTickets for help on using tickets.
Back to Top