Re: [Django] #35737: Clarify where `models` comes from to understand missing import statement in tutorial 7 (was: Missing import statement in tutorial)

[Django]

#35737: Clarify where `models` comes from to understand missing import statement in
tutorial 7
--------------------------------------+------------------------------------
Reporter: Mariatta | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* stage: Unreviewed => Accepted
* summary: Missing import statement in tutorial =>
Clarify where `models` comes from to understand missing import
statement in tutorial 7
* type: Bug => Cleanup/optimization

Comment:

Hello Mariatta! Thank you for taking the time to create this ticket.

I absolutely see how the example you provided could be confusing to some
readers. On the other hand, the tutorial tries to prioritize clarity and
focus on each tutorial part, and on each code snippet. This has a
consequence that each code snippet (usually) builds on top of a previous
one, but is not 100% complete in terms of imports.
The Tutorial parts are designed in a way that if the reader builds their
code from scratch part after part, they end up with complete and correct
code. The con is that every code snippet can not possible list all needed
imports because the size of the snippet would grow considerably, and we
risk confusing the user when it comes to understanding "what's new, what
changed" from previous versions.

Having said this, I think we could improve this specific section by saying
something similar to what other parts already include:

"You can improve that by using the display() decorator on that method
(extending the existing polls/models.py that was created in Tutorial 2),
as follows:"

(For example, Tutorial 5 says "In Tutorial 4 we introduced a class-based
view, based on ListView: <incomplete code snippet follows>".)

The same strategy could be applied in other parts of the tutorial. I'll
accept the ticket on that basis. Would you like to prepare a patch?
--
Ticket URL: <https://code.djangoproject.com/ticket/35737#comment:1>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.